Generating XML Documentation with Sandcastle

One of the most useful features of Visual Studio 2005 (and 2008) is the ability to decorate classes, methods and properties with comments and automatically generate an XML file containing this documentation.

For example, a class can be commented using the summary tags:
XML Documentation

In addition, methods may have even more tags for each parameter or type parameter. For example:
XML Documentation

That can look intimidating at first (lots of XML tags to remember), but it’s really easy — Visual Studio recognizes that when you position the cursor right before a class or method name and type “///”, it will automatically generate all of the correct tags for you. As if that wasn’t enough, there is Intellisense inside of the XML comments to help select which tag to use:
XML Comment Intellisense

Further still, I highly recommend using the excellent GhostDoc plugin by Roland Weigelt to automate the process even further. It uses a number of heuristics to “guess” what you’re trying to say. It adds a convenient “Document this” item in the right-click menu.
GhostDoc\'s \"Document this\" Menu
After clicking “Docment this” on this particular sample of code, Ghostdoc inserted this, which now only required minor edits to make correct.
Documented with GhostDoc
I like this a lot, especially since it lowers the time investment necessary to create good well-written documentation. If you get in the habit of documenting something as you write it (and are thinking about it), you take almost no performance hit.

Visual Studio lets you turn on XML Documentation generation in the project’s Build tab. Just check the box and give it a filename.
Build Tab
When you build your project, this XML file is created and contains information about every XML comment in the entire project.

By itself, this XML file is pretty useless. You can’t do anything with it — can’t search it, can’t easily view it, nothing. We need another tool that takes this XML file and produces something useful like HTML pages. This is exactly where Sandcastle comes in.

Sandcastle can use a number of XSLT transforms to turn the XML documentation file into a number of useful artifacts. For example, you could generate a complete website of your documentation, or compile those HTML files into a CHM (compiled HTML) help file. You can even create help files that can integrate into the MSDN documentation. (Note: If you’re interested in creating CHM file, you’ll need to have HTML Help Workshop installed. It’s rather old, but still works fine.)

Unfortunately, this isn’t the end. Sandcastle is still (after 2+ years) not well integrated into either Visual Studio or the build process. It is mainly a set of command-line scripts to do the transformation. Noticing this deficiency, Eric Woodruff started the Sandcastle Help File Builder (SHFB) project to provide an easy-to-use GUI for Sandcastle. Any installation of Sandcastle is not complete without SHFB.

Interestingly enough, SHFB should be familiar to anyone who used NDoc in the past. Alas, the NDoc project is now dead, having never fully been updated from .NET 1.1 to .NET 2.0. In a bizarre twist of events, the original developer received threats and completely threw in the towel.

I’m actually rather bitter about the whole NDoc ordeal, especially since it was a much-superior and mature project (even 2 years ago) as compared to Sandcastle. My main beef with Sandcastle is how utterly slow it is. This mainly stems from the fact that it adds links to the official MSDN documentation for types and methods that are part of the base class libraries. The way in which it does this is by querying a webservice to retrieve the convoluted URL names (arjeushaklkjegshslaerljkaglkahaejustmakingthisupcuzitssomekindofhash.html). I think that there was so much outcry from the community that the MSDN folks revered back to “friendly” URLs like http://msdn.microsoft.com/en-us/library/system.componentmodel.backgroundworker.aspx
Just for comparison, if NDoc could compile an XML file for a reasonably-sized class library in 1 minute, it would take Sandcastle over an hour (at least). Sandcastle may have made some vast improvements lately, but it still seems rather “kludgy”. Call me old-fashioned, but I’d go back to NDoc any day (if it only supported .NET 2.0 things like Generics properly).

I’ve also noticed a number of up-and-coming projects centered around making Sandcastle more approachable. Of particular note is DocProject, which adds a “documentation project” into your solution much like you’d have a C# Libarary project or a WinForms application project. You can set it so that it only builds in Release (not Debug) mode, and set its project dependencies. I’ve only used it once, and it was still very “beta”. I think they’re still working on Visual Studio 2008 support right now. I’ll keep an eye on how it’s progressing.

At one point there was an MSBuild script for Sandcastle, though I’m not sure what its status is. It hasn’t been updated in awhile. It would be nice if they added (and supported) this along with the MSBuild Community Tasks, but I digress. :)

So, that being said, I’d found that a combination of GhostDoc, Sandcastle, and Sandcastle Help File Builder provide a great combination for generating CHM help files of my class library documentation. Has anyone else had a similar experience, found a better combination, or run across any other useful documentation-generation tools?

Hope that helps!


You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

AddThis Social Bookmark Button

2 Responses to “Generating XML Documentation with Sandcastle”

  1. Have you tried doxygen instead of sandcastle? http://www.stack.nl/~dimitri/doxygen/

    It takes a bit to learn and get running but I’ve always been happy with the output.

  2. Jeff, thanks for the tip about Doxygen.

    Actually I have used Doxygen in the past, but that was over 2 years ago. At that point the C# syntax parser wasn’t quite up to par and things looked a little strange. Perhaps they’ve made a lot of improvements and warrant another look.

Leave a Reply