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 ...

Get Object-Oriented Programming with Visual Basic .NET now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.