Visual Studio Hacks

Master C# XML Comments #68

Chapter 8, Comments and Documentation

|

279

HACK

/// <list>

/// <listheader>

/// <term>Number</term><description>Direction</description>

/// </listheader>

/// <item>

/// <term>1</term><description>North</description>

/// </item>

/// <item>

/// <term>2</term><description>South</description>

/// </item>

/// <item>

/// <term>3</term><description>East</description>

/// </item>

/// <item>

/// <term>4</term><description>West</description>

/// </item>

/// </list>

/// </param>

public void Turn(int Direction)

Both types of lists can be very valuable in commenting your source code.

Custom tags. I mentioned earlier that you can create your own custom tags

to be used in the XML comments. Here is an example of custom tags being

used:

/// <summary>

/// This method retrieves the owner of this vehicle

/// </summary>

/// <returns>The userID of the vehicle's owner</returns>

/// <database>

/// <sproc>usp_GetOwnerIDByVehicleID</sproc>

/// <params>

/// <param>VehicleID</param>

/// </params>

/// </database>

public int GetOwnerID( )

But remember that you would then need to write something to make use of

these custom tags (or customize an existing tool). Although this is some-

thing that I won’t be covering in this book, if you are skilled in XSLT, it is

not that hard.

Creating the XML File

After marking up your code files with XML, the next step is to have Visual

Studio create an XML file including all of these comments. ...