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?

Installation
SandCastle is really quite easy to install. To begin, download it from Microsoft's site -- the most recent available version at this time is "Sandcastle - March 2007 Community Technology Preview (CTP)."

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.

Usability
In terms of usability, SandCastle still has a long way to go before it is as easy to use as NDoc. There are more than 10 steps that must be executed, in a synchronized sequence, to construct the documentation for an assembly.

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
SandCastle's usability issues continue when you try to integrate it with Nant. You must prepare, for each component, a batch to generate the documentation and the Nant's build file can call this batch.

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
The output of SandCastle is slighty different from NDoc's output. All the same elements are there, but they are expressed in a few different ways:

• Fonts and other styles are different.
• SandCastle's output is more dynamic and is ready to swap styles based in the language that you will utilize to consume the documented component (not the language in which the component was written)
• NDoc outputs hierarchies as trees, while SandCastle outputs them as single statements written in the language that is currently selected.

All in all, these are relatively minor differences, but they make SandCastle's output seem more polished than NDoc's.

New Features
The most interesting feature of SandCastle is its complete support for documenting .NET 2.0 features, like generics. In cases like this, new XML Tags (like "typeparam") are completely supported and they have their own place in the tool's output.

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
Considering how difficult it can be to handle SandCastle, I've developed two tools that you can use as you want, without any restriction.

• Compatibility: Tools were compiled with nant.core.dll shipped with Nant version 0.85 RC4.
• Installing: Copy the 3 files (sandcastle_task.dll, scastle_console.exe and nant.core.dll) to the ProductionFolder of SandCastle's installation. If you're using other version of Nant you should copy your own nant.core.dll where indicated.
• Using From Nant: Attached with this review is a version of Config Manager Version 2.0. I've already modified its build file with a new target: "sandcastle". You can examine it to see how easy is to construct documentation using SandCastle and this tool. The target needs a property ("SCastle") declared earlier in same file that can be overridden in the TopCoder_Global.build file.
• Using From Windows Prompt: The other tool (scastle_console.exe) is designed to be executed directly from the Windows command prompt. It expects the path to the assembly to document and, optionally, some other arguments. You can type "scastle_console" to see other available options.

Conclusion
In considering SandCastle, it's worth remembering that it is in pre-production stages. It can change (and really, it has changed from earlier versions) and we must take this fact into account. Microsoft is promising to release SandCastle into production with some additional tools (which are as yet unknown) to make it more usable, and it has promised to include some kind of integration with Visual Studio.