Friday, 13 April 2007

Create .NET Documentation with Microsoft's Sandcastle

Over at Builder.com, Tony Patton has said that from its beginning, the .NET Framework allowed C# developers to use XML-style comments in their code. This feature was added to VB.NET with version 2.0. The compiler can use these comments to generate basic technical documentation. The end result of using the XML commenting feature is a large XML file that is less than user friendly.

Developers wanted and needed another tool to take the XML and create something readable. The open source project NDoc answered the call by enhancing and simplifying the process and facilitating various help file formats. Unfortunately, this project recently ended because the creator received little or no assistance from the development community.

As the demise of NDoc was announced, Microsoft released the first version of its documentation tool called Sandcastle. It is a documentation compiler for managed class libraries. It also processes source assemblies via reflection and uses the XML comments within the code to generate MSDN-style documentation, which is more user friendly than hard-to-decipher XML. Microsoft says it used it internally to build the .NET Framework documentation.

Sandcastle works with the .NET Framework 2.0 (with instructions available online for working with version 1.1) and the .NET Compact Framework. Sandcastle supports localisation and offers a basic command-line compiler interface, as well as a Visual Studio add-on.