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 the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.