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><</description></item>
/// <item><term>^g</term><description>></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)
{
try
{
//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", "\\");
}
catch
{
}
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!
