Jul 27

Posted by: Andrew Nurse
7/27/2006 

I've been following the latest developments in the MSDN Documentation Forums where there has been a lot of discussion over the issue of generating good documentation for .Net 2.0 Assemblies.

VB and C# both support the usage of "Documentation Comments" which are special comments in the code that are designed to be extracted out and used to generate documentation for developers who want to use the Assembly. Until .Net 2.0, NDoc was the best option for taking this documentation info, combining with information gathered from the code itself (through .Net Reflection) and creating nice HTML documentation for the code.

However, NDoc does not support .Net 2.0, and development has hit a roadblock with its leader announcing the project's official "death". Leaving us with no free tools to use (there are some commercial ones, but they're a bit pricey). So basically, developers writing .Net 2.0 code have been without a good documentation tool...until now!

Microsoft has decided to take the tool they use to generate the MSDN documentation developers know and love and release it to the public. Codenamed Sandcastle, this "tool" (and I use quotes because its actually a few tools strung together in the good ol' command prompt) fills the gap created by the loss of NDoc.

I've run it through a few assemblies and I must say that despite the fact that it takes some command line magic (although Scott Hanselman, among others, has put together a script for automating the process) to use, the process is quite straightforward and generates good looking documentation.

The official Sandcastle Blog has more information on the project and the current CTP release.

Links:

• Official Sandcastle Blog: http://blogs.msdn.com/sandcastle
• MSDN Documentation Forums: http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1
• Scott Hanselman's PowerShell Script: http://www.hanselman.com/blog/SandcastleMicrosoftCTPOfAHelpCHMFileGeneratorOnTheTailsOfTheDeathOfNDoc.aspx
• Demise of NDoc: http://haacked.com/archive/2006/07/26/TheDemiseOfNDocAndAChallengeForUsersOfOpenSourceSoftware.aspx
• Batch File for Microsoft Sandcastle: http://ixnay2infinity.blogspot.com/2006/07/batch-file-for-microsoft-sandcastle.html
• Sandcastle Helper: http://www.dotnetjunkies.com/WebLog/mikaels/archive/2006/07/30/142960.aspx