Documenting .NET Framework Source Code with XML Comments
page 2 of 5
by Brett Burridge
Average Rating: This article has not yet been rated.
Views (Total / Last 10 Days): 32767/ 58

Commenting C# .NET Framework source code

C# has supported the XML comments system since version 1.0 of the .NET Framework.

XML comments are added to source code by prefixing the XML comment lines with three forward slashes. Visual Studio will automatically insert a documentation template whenever three forward slashes are typed within a C# source code file. Visual Studio's intellisense system also works within XML comments, using the comments to enhance the information presented about a class, constructor or other member.

Although these comments can potentially be added to the source code at any point, it is usual to ensure that documentation is inserted immediately before the definition of classes, functions, subroutines and properties, thereby allowing these members to be documented. An example of a function documented with XML comments is shown below.

Figure 1

/// <summary>
///<para>Non-HTML files like Adobe Acrobat PDF files and Word
///documents are stored with their original URLs partially
///encoded in their filenames. This function will return the
///original URL of the file.</para>
///<para>The encoding done by the Index Server Companion removes
///characters that cannot be present in Windows filenames
///(these are: \/:*?"<>|). The decoding performed is:</para>
/// <list type="table">
/// <listheader><term>Find</term><description>Replace</description></listheader>
/// <item><term>^f</term><description>\</description></item>
/// <item><term>^b</term><description>/</description></item>
/// <item><term>^c</term><description>:</description></item>
/// <item><term>^s</term><description>*</description></item>
/// <item><term>^q</term><description>?</description></item>
/// <item><term>^d</term><description>\</description></item>
/// <item><term>^l</term><description>&lt;</description></item>
/// <item><term>^g</term><description>&gt;</description></item>
/// <item><term>^p</term><description>|</description></item>
/// </list> 
/// </summary>
/// <param name="FileName">The document's original filename.</param>
/// <returns>Decoded filename</returns>
/// <exception cref="System.Exception">Throws an exception when something goes wrong.</exception>
private string CreateURLFromFileName(string FileName) 
//Remove o_ prefix from URL
FileName = FileName.Substring(2, FileName.Length - 2);
//Remove other encoded characters
FileName = FileName.Replace("^f", "\\");
FileName = FileName.Replace("^b", "/");
FileName = FileName.Replace("^c", ":");
FileName = FileName.Replace("^s", "*");
FileName = FileName.Replace("^q", "?");
FileName = FileName.Replace("^d", "\"");
FileName = FileName.Replace("^l", "<");
FileName = FileName.Replace("^g", ">");
FileName = FileName.Replace("^p", "|");
FileName = FileName.Replace("^f", "\\");
FileName = FileName.Replace("^f", "\\");
FileName = FileName.Replace("^f", "\\");
FileName = FileName.Replace("^f", "\\");
return FileName;

This example shows that as well as a general description of the function's purpose, the function's arguments and return values can also be documented using standard syntax. There are also clearly defined standards for cross-referencing the documentation, adding hyperlinks, lists, tables and code samples. The MSDN documentation for the .NET Framework describes the entire XML comment standard markup supported by the .NET Framework. It is also possible to use your own XML tags within the comments.

If that all looks like hard work, then it is possible to use an application, such as the GhostDoc add-in for Visual Studio, that makes an attempt at writing your XML comments for you!

View Entire Article

User Comments

No comments posted yet.

Community Advice: ASP | SQL | XML | Regular Expressions | Windows

©Copyright 1998-2023  |  Page Processed at 2023-10-03 10:21:01 PM  AspAlliance Recent Articles RSS Feed
About ASPAlliance | Newsgroups | Advertise | Authors | Email Lists | Feedback | Link To Us | Privacy | Search