Documentation tools

At this point I would like to be able to say that there was an excellent tool to convert your XML comments into full formatted help files. Many would say that there is and it is called, or rather codenamed, “Sandcastle”.  You can download an installer and the source code if you need it from:

http://sandcastle.codeplex.com/

The project is still going strong but currently it is making slow progress towards any integration with Visual Studio and for a documentation tool its own state of documentation is, or should be, embarrassing.

The actual tool itself is a command line application which takes an unforgivably long time to learn and use. There are third party GUI interfaces designed to make Sandcastle easier to use, notably Sandcastle Help File builder which is also free to download from the CodePlex site. This works reasonably well but it’s another download and another install and for something that is supposed to be used in a professional environment it all lacks polish. Microsoft and/or the open source team working on it really needs either to take this software seriously or create something better to build into VS 2010.

It is worth saying that Sandcastle goes well beyond simply using the XML comments to build HTML documents. It also uses reflection to get additional information from the .NET assemblies and it can produce end user documentation by compiling files in Microsoft Assistance Markup Language (MAML), which is another XML based help file authoring language.

If you want to try out Sandcastle the simplest way is to download and install and the latest version and a copy of Sandcastle Help File Builder (i.e. don't try and use the raw application):

http://shfb.codeplex.com/

There are other useful utilities that can make using Sandcastle easier but these are described in the Sandcastle Help File Builder help file and you can try them out once you have everything working.

Assuming you have added XML comments to your project and enabled XML help file generation you should be set to try it all out at this point.

Start by opening the Sandcastle Help File Builder and create a new project using any suitable name e.g. MyHelp. Next use the Project Explorer to add the assembly of the application you are documenting;  right click on Document Sources and add either the .exe, .dll or the project file. Also add add any XML documentation files you might have prepared.

From here you can just accept the default settings and build the help file. This takes longer than you might imagine even for a trivial test example because reflection is used to create documentation that includes all of the methods and properties of any framework classes that you might have used. In short, the default result is often more that you expect or want.

However, if you look carefully you will find the XML comments that you have added to your custom methods and properties.

Where next?

What you will also discover is the generated documentation has an unexpected depth given how little effort you have put into creating it.

Perhaps this is enough to forgive Sandcastle its shortcomings, but you could also conclude that it gives a tantalising view of what could be if only the documentation tool was itself well documented and had a good user interface.

There are other auto-documentation tools for .NET for example GhostDoc which is available as a free and paid for Pro edition.  

If you would like to be informed about new articles on I Programmer you can either follow us on Twitter, on Facebook, on Digg or you can subscribe to our weekly newsletter.

<ASIN:067232797X>