Introduction
Every developer relies on a development platform; the two major ones being .NET and J2EE. The development platform provides the basic plumbing, such as file IO, threading, XML processing, and much more so we developers don’t have to worry about the low-level plumbing itself. You use the classes and methods provided by the development platform. Both platforms have a rather large class library and you rely on a comprehensive documentation to understand it and to be able to use it. The same holds true for your own projects and products. Every product needs to constantly innovate and be expanded to survive in the market place. This means your own class library is growing and you get quickly to the point where your team also relies on good documentation to be able to understand, use, and improve it. This holds very true when you bring in new team members.
We all understand the need to comprehensively document our class libraries and to keep them up to date with the code base. And still, documentation is an ongoing pain for all of us. We want better documentation about the development platform we use and your team requires better documentation about each others code. Many people experienced the pain trying to keep external documentation up to date with an ever changing code base and also finding the right documentation when looking at some piece of code. The Visual Studio .NET IDE takes a first big step in easing that pain. It allows you to document your code in a way that the compiler can create an XML document describing your classes, methods, properties, and so forth. This article explains how to use this feature and then create a basic help file out of it.
How to Create XML Documentation Tags in VS.NET
How this works is that you document your code using XML tags and, when you compile your project, the compiler looks for those tags and uses them to create a XML file describing your classes, methods, properties, and so on. This has been available in C# since Visual Studio .NET 2003 and in VB.NET since Visual Studio .NET 2005. In an empty line above your class, method, or property declaration, type three slashes in C#, or three apostrophes in VB.NET. The IDE now creates a XML structure in front of your class, method, or property that exactly reflects its signature (see example below). You then type in the documentation of the class, method, or property.
/// <summary>
/// the form that allows you to choose the XML and XSLT document
/// and then perform the transformation to create the help page
/// </summary>
partial class CodeDocumenter : Form
{
/// <summary>
/// user can choose the XML source file to use
/// </summary>
/// <param name="sender">event sender</param>
/// <param name="e">event arguments</param>
private void SourceFilePicker_Click(object sender, EventArgs e)
{
}
}
Methods have also an XML property tag for each argument. This allows you to describe each argument in detail. It also creates an XML tag for the return value itself so you can describe the expected return value. Any change to the method signature also requires keeping the XML tags in sync. It is also important to keep the order of the XML tags describing each argument in sync with the order of your arguments in the method signature. So, if you add a new argument at the beginning of your method signature, you also need to add the XML tag describing this argument before all the other ones. First, add a new line at the appropriate position, which already adds the three slashes or apostrophes for you. Then, type the left angle bracket (<), which opens up an Intellisense menu and shows you the “param name = ‘argument name'”. Select it and add the right angle bracket (>); the IDE creates the complete XML tag for you and you add the description.
The Intellisense menu also shows additional XML tags that are available. You can, for example, add a permission tag describing the permissions callers need to have to call and execute the method successfully. You can use the example tag to show an example how to use the method, and so forth. This makes it very easy to document your classes, methods, and properties comprehensively.
How to Create the XML Documentation File
You need to tell the compiler to create an XML documentation file using all the XML documentation tags you added in your code. You can do this through your project properties. The steps are different for VB.NET and C#. In C#, select the “Build” tab and, under the “Output” group, select the “XML Documentation File” option. Beside the option is a textbox with the path and name of the XML file. This is set by default to the same path where your binary is created plus the project name as the file name, for example “binDebugCodeDocumenter.XML”. In VB.NET, select the “Compile tab” and, at the bottom, check the “Generate XML documentation file” option. This creates the file at the same location where your binary is created, which is by default the BIN folder under your project folder, an XML documentation file (the same name as your project file). Next, compile your code and look for the XML documentation file. Here is a sample XML documentation file for the code snippet shown above.
<?xml version="1.0" ?>
<doc>
<assembly>
<name>CodeDocumenter</name>
</assembly>
<members>
<member name="T:CodeDocumenter.CodeDocumenter">
<summary>
the form that allows you to choose the XML and XSLT
documents and then perform the transformation to create
the help page
</summary>
</member>
<member name="M:CodeDocumenter.CodeDocumenter.
SourceFilePicker_Click
(System.Object,System.EventArgs)">
<summary>
user can choose the XML source file to use
</summary>
<param name="sender">event sender</param>
<param name="e">event arguments</param>
</member>
</members>
</doc>
Any missing XML tag or mismatch between the XML tags and class, method, or property signature will be show as a warning. It is important to resolve this to assure that documentation and code stay in sync. As soon as your team gets negligent on that, you will see the documentation becomes less and less valuable until you reach the point that it is out-of-sync and no longer used. This is a discipline you need to instill in your development team.
How the Visual Studio .NET IDE Uses the XML Documentation File
The Visual Studio .NET IDE also takes advantage of the XML documentation file. The Intellisense feature of the IDE will look for the XML documentation file at the same location as the referenced binary file. If present, it will use the XML documentation file when showing the Intellisense and show right in your IDE your descriptions of the classes, methods, method arguments, return values, properties, and so on. This can be extremely useful for other teams and team members. You get helpful information shown right when you have a need to use the class, method, or property. So, when distributing your binaries to other teams or team members, make sure to pass along the XML documentation file. They will appreciate that little bit of convenience.
How to Create a Help File for Your Code
You can use the same XML documentation file to create help files describing your code. This is useful if you are selling components within the developer community. But, it is also useful to create help files describing your code each time you create a release. It can be used by your support teams, integration partners, or by your sustained maintenance team (the team that does the bug fixing after a release). The biggest advantage of this approach is that code and documentation are kept in sync. Even if you have separate technical writers creating your code documentation, they can still use the help files generated out of the XML documentation files as a starting point. This cuts down the time they need to gather information.
The simplest way to create a help file is to apply an XSL transformation to the XML documentation file that creates a HTML file. The enclosed tool allows you to select an XML documentation file, an XSL stylesheet, perform the transformation, and save it as an HTML help file. Here is how the XSL stylesheet provided by the tool works. First, the template for the matching root node gets called. This one selects all assembly nodes and calls its associated template.
<!-- root node: calls the assembly match which then calls the
members match -->
<xsl:template match="/">
<xsl:apply-templates select="//assembly"/>
</xsl:template>
The assembly template includes the CSS stylesheet provided by the tool. The tool creates a copy of that CSS stylesheet at the same location it saves the generated HTML help file. All HTML code generated references styles defined in the CSS stylesheet, so it becomes easy to change the formatting of the generated help file later on. Next, it creates an HTML table to describe the assembly. It then displays the assembly name in the first row of this table. Nextn it selects all member nodes that have a name attribute containing the “T:” characters. The XML documentation file adds all types as member nodes with a name attribute always starting with “T:”. So, effectively, we select all types and call its appropriate template.
<!-- assembly: build the help table with the title of the
assembly -->
<xsl:template match="assembly">
<LINK REL="STYLESHEET" TYPE="TEXT/CSS"
HREF="HelpStyleSheet.css"/>
<TABLE CLASS="AsemblyTable" CELLPADDING="2" CELLSPACING="0">
<TR CLASS="AssemblyHeader">
<TD COLSPAN="3">
<xsl:text>Assembly </xsl:text>
<FONT CLASS="Title"><xsl:value-of select="name"/></FONT>
</TD>
</TR>
<xsl:apply-templates select="//member[contains(@name,'T:')]"/>
</TABLE>
</xsl:template>
