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.
This was first published in July 2008