Generating Documentation with Sandcastle
Sandcastle is a free toolset released by Microsoft for constructing professional-looking, MSDN-ish documentation for managed code libraries. It is also used by Microsoft to construct the .NET framework documentation. The toolset is currently in its CTP phase (for over a year now), but a community is beginning to form. The latest release is the October 2007 CTP (look for further announcements on the Sandcastle blog or the Sandcastle CodePlex project).
Here's what the results look like for a sample project I've generated (in HTML Help 1.x format, which produces a CHM):
(Full disclosure: in the past, I've used Document! X, a commercial documentation solution by Innovasys Ltd. It certainly does the job, although at a fairly high cost - $585 per user. The GUI used to have some issues, but I suppose they have been resolved in the newer versions.)
Generating documentation using Sandcastle is not very trivial at the moment if you only use the released toolset from Microsoft (this will certainly improve as the project progresses). Fortunately, there are at least three community projects designed to bridge this gap. I've decided to use all three and see how relevant they might make Sandcastle, even today. My test harness was a simple solution with three projects, two written in C++/CLI and one in C# (all .NET 2.0, Visual Studio 2005). So without further ado:
DocProject
DocProject was the last option I chose to evaluate. The approach is slightly different and interesting here: instead of using a stand-alone tool for generating documentation, you simply insert a special Visual Studio project into your solution. That Visual Studio project can now be linked to the outputs of other projects in your solution and automatically generate documentation for these outputs. Adding that special DocProject project was a snap with a convenient graphical wizard, and the generated documentation was great.
Sandcastle GUI
Sandcastle GUI has a simplistic, grayish UI which you use to select an assembly directory and then let the tool generate the documentation for you. Unfortunately, Sandcastle GUI was unable to generate documentation for my C++/CLI projects. That it to say, it did generate the classes, but it didn't add the XML documentation comments I've worked so hard to sprinkle all across the project. The one thing I did like is the fact the tool didn't require any additional installation. It can also be run from the command line, which gives you hope if you need to integrate it in your build process.
Sandcastle Help File Builder
SFHB has a simplistic, grayish UI (quite similar to Sandcastle GUI), but it gives you more ability to customize the output and worked just fine with my C++/CLI projects.