O'Reilly logo

Object-Oriented Programming with Visual Basic .NET by J.P. Hamilton

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required