Documenting .NET Code

In this article I would like to introduce the special topic in .NET world: documentation. If you are new to programming and are working on a bigger project, please get used to documenting your code. There are many excellent guides out there explaining what good documentation is and you should read them. I will talk about .NET specific documentation feature, XML comments. This type of documenting is excellent in providing a guide to your created classes and their properties and methods. If you use XML comments, you can easily generate .chm files that look exactly the same as MSDN provided documentation! Isn't that awsome? Just use xml, compile the files using /doc switch and then use free tool like NDoc (http://ndoc.sourceforge.net/) to generate .chm files. NDoc actually can generate JavaDoc style documentation as well!

How XML Documentation works? Well, the reason why it is called XML is because it is in XML form. Don't worry if you don't know XML, it's not crucial here (although you should know XML as a programmer). I use XML Documentation to document all publicly visible members of my public classes. // or ' comments should still be there explaining your code. However the goal XML documentation is to provide more generic info. Let's take the following C# code as an example:

public LoadDate (string fileName)
{
     // load xml
     XmlDocument doc = new XmlDocument();
     xmlDoc.Load (fileName);
     // ... more work done ....
}

How would I use XML documentation to explain what this method is doing? I would write this:

/// <summary>Loads xml from a file and initialized various data structures
/// obtained from xml file.</summary>
/// <param name="fileName">Name of a file that contains xml.</param>
public LoadDate (string fileName)
{
     // load xml
     XmlDocument doc = new XmlDocument();
     xmlDoc.Load (fileName);
     // ... more work done ....
}

Notice ///. This indicates that the comment is in XML format. In the example you saw two tags: <summary> and <param> There are more:

/// <c></c>
/// <code></code>
/// <description></description>
/// <example></example>
/// <exception cref=""></exception>
/// <item></item>
/// <list type=""></list>
/// <listheader></listheader>
/// <param name=""></param>
/// <paramref name""></paramref>
/// <permission cref=""></permission>
/// <remarks></remarks>
/// <returns></returns>
/// <see cref=""></see>
/// <seealso cref=""></seealso>
/// <summary></summary>
/// <term></term>
/// <value></value>

I will not explain all of them here. You are better off looking at MSDN documentation that is available online. summary, description, remarks, returns, param, and value are the ones used by me most often.

How to generate the documentation from these comments? First of all, you have to set in your IDE (VS.NET or #Develop, or any other) that you want xml file generated that contains the documentation. In #Develop, go to Project, Project Options... and click on Configuration. One of the checkboxes will say "Generate xml documentation". Check it. I'm not sure about VS.NET setting, but it should be somewhere in Project settings or something. Once you have xml file generated, run NDoc, select the assembly that you want to document and its corresponding xml file and build documentation. Play around with that because when you will work on serious project, this will come in handy.