XML Code Comments

 

I made a new-years resolution* to learn more about XML code comments and the associated language – MAML.  To that end, I installed Sandcastle and the Sandcastle Help File Builder  – now found here and here.

I then when to one of my many “Hello World” projects laying around my file system.  The sum total of the project is this:

public class Program
{
    public static void Main(string[] args)
    {
        WriteMessage("Hello World");
        Console.ReadKey();
    }

    public static void WriteMessage(string input)
    {
        if(String.IsNullOrEmpty(input))
        {
            throw new ArgumentNullException("Input cannot be empty.");
        }

        Console.WriteLine(input);
    }
}

Note that the scope of the class and methods are public.

I then went into project properties and checked off  XML Document file:

I then hit F6 and….

How cool is that?  VS2010 tells you if you are missing comments – it keeps track of things so you don’t have to.  So now I have to add some comments.  I went above the class and hit /// and presto-chango, I get an awesome block of code comments.  The other nice thing about this snippet is that if there are parameters, that gets pre-filled for me.  For example, the WriteMessage snippet looks like:

        /// <summary>
        /// 
        /// </summary>
        /// <param name="input"></param>

I then went ahead and added code comments to that method:

        /// <summary>
        /// Writes a message to the console window.
        /// </summary>
        /// <param name="input">The message to be written.</param>
        /// <exception cref="ArgumentNullException">If the input is null or empty.</exception>

Note that when you hit ///, you get an option of a bunch of different kinds of comments.  A full list for is found here.  Also note that my comments are all in grammatically-correct English with punctuation.  Finally note that I use param for the input, not paramref in the summary…

I then added a class-level comment and changed the scope of Main.  I hit F6 and I now have an XML code comment file created and ready in my bin directory.

I then loaded up Sandcastle Help File Builder and created a new project:

I then added a reference to the XML file that was generated by Visual Studio Project Explorer-> Documentation Sources –> Right Click Add.  Then, I hit Build (the two down arrow button) and magic happened – right in front of my very eyes. 

Opening up the .chm file, I got full-blown help file. 

 

There was one problem, as you can read in the output from SHFB:

Warn: ShowMissingComponent: Missing <summary> documentation for N:Tff.VisualStudioBuildExample

And in the help file:

To get around this, I first started trying to add another XML file in addition to the one that VS2010 generated – a XML Document File – You can read about it here.   I futzed around with it for a bit and then gave up.  I then just added the values a properties in SHFB here:

‘

Clicking on the ellipses, you get this dialog where you can enter in your summaries:

And then you get the namespace comments:

 

* Nepali New Year is celebrated on the 1st of Baisakh Baisākh (12–15 April) in Nepal. Nepal follows Vikram Samvat (विक्रम संवत्) as an official calender. (Not to be confused with Nepal Era New year).  Thanks Wikipedia!