TopCoder is currently using NDoc as the de facto tool to generate documentation for .NET projects, using XML tags written in the component's source code. But NDoc, a freely available tool, has been without support for some time, and lacks support for the new features in .Net Framework version 2.0, including generics and new XML documentation tags.
Microsoft is offering a free download (free for now, at least) of SandCastle, a tool that generates documentation in much the same way that NDoc does. Unlike NDoc, though, this tool is very well supported -- SandCastle is used internally by Microsoft's people to generate documentation for their projects, so we can expect that this tool will be constantly supported and that it will gracefully handle new features from future releases of the framework. How does SandCastle stand up?
Simply execute the downloaded installer to have SandCastle ready to be used. You must remove previous versions of SandCastle before starting the installation of this version. In addition, note that SandCastle requires the hhc.exe file from HTML Help Workshop. If you're using NDoc now, you probably already have hhc.exe installed in your system. If not, you must download and install the HTML Help Workshop before you can run SandCastle.
Most of these steps are utilizing pieces from SandCastle installation; other steps are using pieces from actual path, and other from fixed locations. To run SandCastle as currently provided by Microsoft, you must copy the sample's batch file that came with SandCastle to your component's folder, edit it by hand, and cross your fingers, while preparing to debug your effort based on the tool's cryptic error messages.
The good news is that once you have your .bat debugged SandCastle is actually stable. Once you've got it up and working, you can run it with confidence and the knowledge that the output will be consistent with what you should expect.
To simplify the utilization of SandCastle, I've developed a tool (scastle_console.exe) that links all the steps needed to construct the documentation for an assembly. All you should need to provide is the full path to the assembly you want to document and, optionally, the folder where you want to write the output and the framework's version to target. For more information, see the "Installing and Using Tools" section below.
Integration with Nant
To simplify integration with Nant, I've developed a Custom Nant Task that automates all needed operations. With this task, using SandCastle from Nant is easier than invoking NDoc. You only need to point to where the task is, but this is a one-time job if you're using a TopCoder_Global.build file. See "Installing and Using Tools" below for more.
SandCastle's Output vs NDoc's Output
All in all, these are relatively minor differences, but they make SandCastle's output seem more polished than NDoc's.
When analyzing the compiler's output, SandCastle can interpret both the output of 1.1 compilers and the output of 2.0, so both frameworks are supported.
Installing and Using Tools