XML Code Comments and Sandcastle, demystified! Part I

Most developers I think are aware of the concept of using XML code comments to decorate .NET objects. There are really two benefits: 1) it shows this information in intellisense when you’re consuming the object and 2) you can production component documentation like MSDN.

So you type “///” (in C#) above a method or class name and some of it seems intuitive, and it is. But what should you really do – to properly document a component? Secondly – where do you find more information about what tags are supported? Well, after having been hip-deep in this sort of documentation for months, I hope to make this a one-stop-shopping blog post for you! There is very little information on the web, and what is out there, is either incomplete or sometimes not correct.

First, here are the basics… NDoc was around for a while, to generate component documentation and it had it’s set of supported keywords. Then, .NET 2.0 and generics came out and were, apparently, difficult to work with, NDoc couldn’t support them, so that product went away. Meanwhile, someone at Microsoft came up with Sandcastle – or that is what they used internally I think, and they tried to make it open source. They ended up instead just releasing it on the Microsoft site. Now, Sandcastle supports generics, and it seems to support most of what NDoc supported, but some things are a little different. Trying to figure out those differences has been a bit frustrating and again – this post is the conclusions I’ve drawn, after having scoured (what I believe to be) every single online resource that exists on this topic!!

What do you need?

Then, it’s just a matter of using XML code comments in your code, build your project, then use SHFB to add the .dll and generate a .chm (they call it a HtmlHelp1x format). So where to begin? Well, the thing I’ve been looking for, for quite a while is – what are the best-practices around writing XML code comments? These posts are what I’ve found, or what I believe are the best-practices – and I’ve yet to see this compiled in any one place, so hopefully this helps as a jumping off point for you, in your project.

 

How should I document a class?
A class should have a two minimum things: a summary tag and a thread safety tag.

    /// <summary>

    /// Summary

    /// </summary>

    /// <threadsafety static="true" instance="false"/>

Above is the default implementation of threadsafety – it translates to:

image

Ideally though, you should include a remarks section to describe in more detail what the class is for. You can separate paragraphs with the <para> tag. For example:

    /// <summary>

    /// Summary

    /// </summary>

    /// <remarks>

    /// <para>

    /// This is the first paragraph of remarks about Class1.

    /// </para>

    /// <para>

    /// This is another paragraph.

    /// </para>

    /// </remarks>

    /// <threadsafety static="true" instance="false"/>

How should I document a method?
A method is probably the most extensive members to document, because there is a lot going on. So the bare minimum here is a lot, but necessary and helpful for the consuming developer. For a protected or public method, the following should always be documented:

  • <summary> – describing the method
  • <param name=”argument name”> – to describe the purpose of each method argument.
  • <returns> – to explain what the method returns.
  • <exception> – to publish what exceptions might be throw, and for what reasons.
  • <permission> – what .NET permissions are needed to execute this method, if nothing in particular is needed (and you are sure!) – then you might use: <permission cref="System.Security.PermissionSet">Anyone can access this member.</permission>

For example:

    /// <summary>

    /// Do stuff.

    /// </summary>

    /// <param name="numberOfTimes">The number of times to do stuff.</param>

    /// <param name="typeOfStuffToDo">The type of stuff to do.</param>

    /// <param name="stuffDescription">Description of stuff.</param>

    /// <returns>Just returns a <see cref="String.Empty"/> right now.</returns>

    /// <exception cref="ArgumentException">If <paramref name="stuffDescription"/> is null or empty.</exception>

    /// <permission cref="System.Security.PermissionSet">Anyone can access this member.</permission>

    public string DoStuff(int numberOfTimes, StuffType typeOfStuffToDo, string stuffDescription)

    {

        if (string.IsNullOrEmpty(stuffDescription))

            throw new ArgumentException("Argument ‘stuffDescription’ cannot be null or empty.", "stuffDescription");

 

        for (int index = 0; index < numberOfTimes – 1; index++)

        {

            // Do stuff

        }

        return string.Empty;

    }

This translates to something like this:

image

As you can see, this gives you a pretty complete page of documentation. It tells you to data types, the return value, exceptions, permissions, etc… And this should ideally be your minimum amount of documentation for a method. The other advantage of publishing the exceptions – is that intellisense shows those as well (in C# only, not in VB). That looks like this:

image

Coming in a future blog post(s):

  • How should I document a property?
  • How should I document an enum?
  • How should I document an event or delegate?
  • How should I document private fields and other private members?
  • How to reference other documented objects?
  • How to include color-coded, language-specific sample code in the help page?
  • How to include a “note” (with icon) within a remarks section

Stay tuned…

Posted in Best-practices, Uncategorized

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Archives
Categories

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 5 other followers

%d bloggers like this: