From time to time, we dig into the Microsoft-supported Open Source Project Community Web site called CodePlex, to see what's new and interesting there (for a discussion of CodePlex and its
origins and content please check out my May 2008 article "Check out CodePlex for a ton
of interesting .NET projects"). The last time we visited, there were about 4,500 projects listed there; this
time, the count has jumped to just over 5,200. Of these thousands of entries, the Sandcastle documentation compiler for Managed Class Libraries is relatively
new, with a first code release in January, 2008, and a second release on May 29, 2008 labeled Version 2.4.10520.
What Sandcastle does is to generate MSDN style documentation, based on reflecting over the source assemblies and
integrating such XML documentation comments as it can find in the code it examines. That said, it works with code
that omits authored comments with equal facility as code that includes them, and works with Generics and .NET
Framework versions 1.1, 2.0, 3.0, and 3.5. Sandcastle itself consists of two primary components, named MrefBuilder
and Build Assembler. MrefBuilder generates a reflection XML file for the Build Assembler, while the Build Assembler
handles syntax generation, document and source code transformation, and the other core activities involved in
creating documentation from source code/manage class libraries. Sandcastle is designed to create Visual Studio and
.NET Framework documentation.
Sandcastle is the work of a Microsoft developer who goes only by his handle, Aram (there are no real clues to his
identity in the source code, though Microsoft does hold the copyright for all published code elements). For months
after the project's initial release, there was considerable hoopla because the developer chose not to release the
source code for the project. This changed on July 2, when the source code was posted to CodePlex (you can find it
under the Source Code tab on its project page). This came only after the project had been yanked from the site for
the preceding month, and the ensuing hue and cry led him (and perhaps the powers that be) to reconsider its removal,
and to restore the project along with its source code on that date.
Sandcastle has also proven sufficiently popular to spawn additional projects built upon its platform (which may
also help to explain its recent resurrection). These include:
•A Sandcastle Help File Builder that adds a GUI front end plus project
management features and an automated build process. It also offers both graphical and command line tools to help
developers automate the construction of a help file.
•The DocProject for Sandcastle, which drives Sandcastle help
generation tools through Visual Studio (either 2005 or 2008 will do the trick here) and MSBuild. It supplies a
choice of project templates that will build compiled help version 1.x or 2.x files for all project references.
•Sandcastle Extensions, a project that provides numerous
components missing from the original January Sandcastle distribution, including build components (including added
support for the two preceding projects), plus solutions for help deployment issues.
•Sandcastle Styles: Presentation/style improvements to
maximize the value of XML comments and MAML elements included in code, and used to generate documentation. Examples
to better illustrate these capabilities are under development.
•Sandcastle Assist: Extension libraries and utility classes
designed to simplify the process of creating documentation using Sandcastle that will probably take the form of a
Sandcastle SDK. This offering is slated to include some interesting sounding (but as yet unavailable) packages.
Given the infrastructure that grew up around Sandcastle it's not hard to understand why it came back from the
void. There's enough interesting functionality here to make it worthwhile and to keep it around for some time to
come. Check it out!
Ed Tittel is a writer and trainer whose interests include XML and development topics, along with IT Certification
and information security.
