Object-Oriented Programming with Visual Basic .NET

7.5. Custom Attributes

C# excels over VB as a .NET language in one particular area: XML documentation comments. C# allows you to embed XML comments into your code that can be compiled to documentation independently at a later time. Example 7-6 shows a simple class written in C# that contains XML comments.

Example 7-6. C# class with XML comments

using System; /// <summary> /// Summary for the BestLoveSong class. /// </summary> /// <remarks> /// This is a longer description for the BestLoveSong class, /// which is used as an example for Chapter 7. /// </remarks> public class BestLoveSong { /// <summary> /// Name property </summary> /// <value> /// Returns the name of the best love song.</value> public string Name { get { return "Feelings"; } } /// <summary> /// Plays the best love song.</summary> /// <param name="volume"> Volume to play the best love /// song.</param> public void Play(byte volume) { if (volume > 11) volume = 11; } }

You can compile this example from the command line using the /doc switch of the C# compiler as follows:

C:\>csc /target:library comments.cs /doc:comments.xml

Using this switch produces an XML file named comments.xml, as shown in Example 7-7.

Example 7-7. XML documentation output

<?xml version="1.0"?> <doc> <assembly> <name>comments</name> </assembly> <members> <member name="T:BestLoveSong"> <summary> Summary for the BestLoveSong class. </summary> <remarks> This is a longer description for the BestLoveSong class, which is used as an example for ...