VS.NET 2005 Basics Part 1: XML Documentation, Intellisense, and automatic documentation generation

XML documentation is an insanely great feature of Visual Studio.  

Why? In a word, Intellisense. If you're a total newbie, welcome. Intellisense is simply a collection of informational popup windows that appear while you're programmming, and these popups contain extremely useful information relating to the code you are trying to write. Intellisense saves time, jogs your memory, and helps you write code accurately. If you have written or have inherited a complex hierarchy of reusable programmatic classes, Intellisense will help you remember the organization and needs of that class structure.

If you document your code using VS.NET's simple XML-based tagging, you'll be continually prompted with Intellisense windows with information about what your code does. You can integrate your own writing and documentation into the experience of working with the VS.NET tool. This is so powerful.

 A few examples and screenshots will really help explain things here.

Long ago I wrote a class called "FileOps," which is a grab-bag of very useful functionalities (methods AKA functions) relating to file operations on our web application server. I commonly use these methods in my web application work, so I've put the FileOps class in a subfolder of my App_Code folder so it is available to be used by any of my applications.

One of the methods (functions) in that class is CreateYearAndMonthDirectoryBasedOnDate(). This method creates and helps maintain an organized file structure on our server's file system, arranging it in a useful hierarchy similar to the folder structure illustrated below:

Let's have a look at some of the code for that method now. The code includes a bunch of comments structured as XML, positioned just prior to the code that defines the method. These comments document different aspects of the method's operation, including its parameters (inputs) and return type (output.) Structuring your documentation in this particular way is extremely useful if you're working in Visual Studio. We'll soon find out why.

   /// <summary>
    /// <para>Creates a hierarchical folder structure corresponding to a year and month on a server filesystem, e.g.</para> 
    /// <para></para>
    /// <para>c:\basePhysicalDirectory\2007\July\</para>
    /// <para></para>
    /// <para>You can subsequently copy files into these folders, creating an automatically organized folder structure. </para>
    /// <para>If the folder already exists, then it will simply return the path to the existing directory.</para>
    /// </summary>
    /// <param name="inputDate">DateTime upon which to base the creation of the new folder</param>
    /// <param name="basePhysicalDirectory">The base physical directory on the server filesystem that will be used to create the year and month folders.</param>
    /// <returns>Returns a string corresponding to the newly created (or existing) path on the server filesystem.</returns>
    public static string CreateYearAndMonthDirectoryBasedOnDate(DateTime inputDate, string basePhysicalDirectory)
    {
        string yearDirectory = Path.Combine((basePhysicalDirectory), ((inputDate.ToString("yyyy")) + @"\"));
        string monthDirectory = Path.Combine(yearDirectory, ((inputDate.ToString("MMMM")) + @"\"));

        if (!Directory.Exists(monthDirectory))
        {
            if (!Directory.Exists(yearDirectory))
            {
                System.IO.Directory.CreateDirectory(yearDirectory);

[etc.]

"So what?" say the cynics. "It's just a bunch of code comments as XML. Big deal." Well... the Good Part comes two weeks or two years later, when I'm trying to use my handy FileOps class in other programming projects. What follows is my view from Intellisense as I call the FileOps class's methods to do some useful work. Below, I'm saving out a programmatically created PDF file, and I want it to be filed in an organized way. I use CreateYearAndMonthDirectoryBasedOnDate() to generate a folder structure on the server based on a database entry associated with the PDF. What I want you to pay attention to here is how VS.NET uses Intellisense and the XML documentation I wrote for the method to give the programmer a step-by-step cue of what she should be doing next.

 
(Step 1: As I type "FileOps", the name of my class, notice I'm presented both a selectable list of all of the classes available to me, and a yellow comment box. The comment box includes an XML comment I wrote that describes the entire "FileOps" class. (Interested in the database abstraction code? Check out the sublime  EntitySpaces Object-Relational Mapping framework ))

 
(Step 2: As I hit the period ".", which denotes the fact that I want to call a method of my FileOps class, the previous Intellisense informational window disappears, and a selection of the methods I have written in the past and associated with FileOps pops up. Note that the XML documentation I wrote earlier to accompany my method is appearing as a comment in Intellisense. Very handy! Anything that reduces the amount of stuff the developer has to keep in her brain at once is a great thing.)
 
(Step 3: I continue typing and am now filling in the parameters that are required by my method. Remember how I described my parameters in XML documentation with the <param>...</param> tags? My context-specific documentation appears right here, right when I want to see it.)

 
(Step 4: When I reach the last parameter that my function requires, again it shows me the descriptive docs I wrote for what the parameter is and does. Sharper-eyed newbies will also notice that the datatype of the parameter is being indicated, which helps remind the finite and forgetful programmer what information the method requires to do its work.)

This is a deliberately simplified example involving straightforward static methods. For many people, Intellisense is old hat and reading "Run Dick Run" above may seem more than a little patronizing. However, I'm surprised how many otherwise smart developers out there don't use VS.NET's XML documentation to describe their classes or methods at all. Makes no sense. This stuff is great: context-specific information when you need it, and changeable as required with very little investment of time.  If you're rooting around for just the right web application technology to learn, Intellisense/VS.NET and this documentation stuff is in itself a compelling argument to take a serious look at ASP.NET.

This XML documentation can also be parsed by external tools and compiled into CHM (Microsoft Help) files, or sets of HTML pages. My understanding is that for a long time the de facto standard for this kind of tool was the free nDoc tool, but as of last summer NDoc is not being developed further. Microsoft is in the process of picking up the external documentation ball with SandCastle, and I imagine we'll see something like it in the next release of Visual Studio.

I'm going to underscore a few things that may not be obvious to VS.NET newbies and newbies at heart.

1) To document your code, get in the habit of hitting three slashes before front of any method, property, class, or other structures in your code files. VS.NET is smart and will figure out what comment types are relevant given where you're at in the code. If you've been hand writing <summary> ... </summary> or <param> ... </param> as XML comments as you've studiously followed some tutorial you picked up somewhere, you have been doing things the hard way. Enter three slashes, and let Visual Studio do the work of writing this cruft for you, including a summary section, a comment for each parameter, and a comment for the return type.

2) The VS.NET Task List is useful, and you can automatically add stuff to the Task List using TODO comments in the correct form. You would think that you might embed todo comments using the same XML patterns, e.g.

WRONG! <todo> Rewrite this method!</todo> WRONG!

This does not work the way you might think. Entering a comment in the following form will automatically place a TODO item on the task list:

//TODO: Rewrite this method. 

Summary of XML comment tags that are parsed by VS.NET
I'm going to borrow the Code Project's excellent, terse summary of tag types and comments about the tags for my own reference. The text below is courtesy of a great article at the Code Project that also describes how to set up NDoc to generate MSDN-style documentation from XML comments.

The summary tag is the most basic of tags. The list below is the complete set currently supported by VS.NET. The ones marked with a * are the ones I feel are the most useful and the ones we will be dealing in the following examples.

c
The c tag gives you a way to indicate that text within a description should be marked as code. Use code to indicate multiple lines as code.

code*
The code tag gives you a way to indicate multiple lines as code. Use <c> to indicate that text within a description should be marked as code.

example*
The example tag lets you specify an example of how to use a method or other library member. Commonly, this would involve use of the code tag.

exception*
The exception tag lets you specify which exceptions a class can throw.

include
The include tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file.

para
The para tag is for use inside a tag, such as <remarks> or <returns>, and lets you add structure to the text.

param*
The param tag should be used in the comment for a method declaration to describe one of the parameters for the method.

paramref
The paramref tag gives you a way to indicate that a word is a parameter. The XML file can be processed to format this parameter in some distinct way.

permission*
The permission tag lets you document the access of a member. The System.Security.PermissionSet lets you specify access to a member.

remarks*
The remarks tag is where you can specify overview information about a class or other type. <summary> is where you can describe the members of the type.

returns
The returns tag should be used in the comment for a method declaration to describe the return value.

see
The see tag lets you specify a link from within text. Use <seealso> to indicate text that you might want to appear in a See Also section.

seealso*
The seealso tag lets you specify the text that you might want to appear in a See Also section. Use <see> to specify a link from within text.

summary*
The summary tag should be used to describe a member for a type. Use <remarks> to supply information about the type itself.

value*
The value tag lets you describe a property. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents.

Resources:
Producing Professional MSDN-style Documentation with .NET and NDoc
http://www.devx.com/dotnet/Article/29646

C# and XML Source Code Documentation
http://www.codeproject.com/csharp/csharpcodedocumentation.asp

NDoc on SourceForge:
http://ndoc.sourceforge.net/

Insightful O'rielly article on NDoc and the problem of documentation generation in general:
http://www.ondotnet.com/pub/a/dotnet/2002/12/09/ndoc.html

Technorati tags: VS.NET 2005, VS.NET, Intellisense, C#, Tutorial, ASP.NET, Newbie, webapps, kenfine, ideapod