MSDN Style Class Documentation

Jan 20, 2010

by: Tim Stanley

web-development

NDoc is dead. Long live NDoc! How to generate MSDN style documentation using Sand Castle on Visual Studio 2008.

History
Code Is The Documentation
Show Me The Code
A New Programming Documentation Era
Give Me That Old Style MSDN Documentation
How To Use Sand Castle
Example
References

History

In the mid 90’s when COM was king, generating API documentation for classes was a tedious and arduous task. The moment the documentation was published, it was often out of date due to changes the development team had already made. One company I worked for in the retail software domain generated an entire toolset (OO TOOL) to diagram, generate code, generate a data model and generate documentation from a single source.

An interesting side note, one of the key members on the OO TOOL team was Mark Collins. Mark worked with me in the UK for two years at Fujitsu / ICL and went on to write several articles and even a book on Windows Workflow. The tool was the first successful attempt I had seen in a Microsoft based project to keep source and documentation updated using automated tools.

When .Net entered the picture, Visual Studio provided an interesting feature to allow code comments in C++/C# to be extracted to an XML file. Not to be out done, VB Commenter came out for VB code and VB programmers to do the same. With code generating XML style documentation, the next step was to convert the documentation to something a little more searchable and user friendly. NDoc came out and was an instant hit. NDoc when combined with the HTML help generator was able to generate compiled HTML output. While a bit of work, it was infinitely better then older proprietary tools and definitely more intuitive than Sand Castle.

When .Net 2 came about, it changed some things that required NDoc to make some fairly non trivial changes. Kevin Downs one of the original NDoc authors decided that amidst personal threats and the additional non paying effort required to go to .Net 2, he decided to discontinue his efforts on NDoc. Compounded by an announcement by Microsoft to create a competing product called Sand Castle, NDoc subsequently died.

Code Is The Documentation

If Sand Castle wounded NDoc then IntelliSense killed and buried it. The MSDN style of documentation is limited in it’s usefulness. It’s too focused on a specific method / property to be helpful, difficult to deploy (even when done as a website) and becomes out of date extremely quickly. When Visual Studio added IntelliSense in 1996, it really changed the way developers used documentation. Books, manuals, API documentation all were used at the time. IntelliSense allowed embedding into a .Net dll all the API information needed in the past and .Net reflection combined with IntelliSense could pull that documentation out and put it directly in the hands of developers.

Show Me The Code

I suspect IntelliSense and the Go To Definition feature of Visual Studio get used more than the MSDN online style documentation. Between the two features, a quick reference to a dll and an appropriate using statement, gives 80% of the information needed to use a class library. Similar in concept to the man page, the IntelliSense documentation provides the documentation you need, when you need it and where you need it.

IntelliSense provides the API documentation like a dictionary provides the list of words for a language. However, it doesn’t tell you how to combined the information together to achieve a specific purpose. The documentation for fopen(), never told you about fflush(). You had to know this or read it in a book or learn it from someone who knew it. Blogs with examples have filled the knowledge gap and when that isn’t enough you can search Stack Overflow for expert help on answers. When IntelliSense documentation is combined with an example or two, we have just about everything needed for the typical class library programmer.

A New Programming Documentation Era

It was subtle at first, but we have transitioned into a new era of programming. With the rapid changes in technology, came a rapid way of keeping the technology up to date. Generated static printed documents no long work in an era when technology changes many times a year.

API documents were replaced by IntelliSense and Go To Definition
Designs can be documented by stub code and XML comments quicker than they can with traditional Word documents.
Books were replaced by Blogs and search engines
Code examples were added to Blogs to explain “How to” use the technology
Code formatters and Syntax Highlighters were added to Blogs to put a more coding friendly face on examples
Questions that were answered by support forums are now answered on Stack Overflow with much better answers than the “support staff” ever were able to provide.

2617720523_57ae50f8a1_o

Give Me That Old Style MSDN Documentation

With all the new advancements in technology, MSDN style documentation can still be useful about 5% of the time to pull an overall view of documentation together or to provide documentation in a form for someone who doesn’t have a dll, but needs to see what a class library can do. Also, sometimes you do get paid by the pound for generating documentation. Then there are those RFP’s that actually want to see a printed form of the documentation that won’t be used by any programmers, but does prove that you have enough staff to generate documentation worthy of purchasing the product.

If you want to pull all the IntelliSense information out into HTML or compiled Html Help, your going to need some help. Microsoft has Sand Castle to build those documents.

How To Use Sand Castle

The first thing to know about Sand Castle is it’s not enough to do the job. You need some tools to help Sand Castle generate the help documentation.

The key steps I used to generate documentation with Sand Castle:

Mark all public classes with XML comments, i.e. ///<summary>Describe the class.</summary>
Download and Install Sand Castle via the MSI.
Download and Install the Sand Castle Help File Builder (SHFB) MSI by Eric Woodruff
Download and Install / Patch the Sand Castle Styles
Run SHFB
Add documentation sources (csproj or dll)
Add references (csproj or dll)
Set the help file format and other SHFB options (I recommend using the MemberName naming method to get html links with names instead of Guids)
Run SHFB build, wait, wait, done

Sand Castle documentation for actually using the product is hard to come by. I did find the Sand Castle GUI tool (located at C:\Program Files\Sandcastle\Examples\generic after installing the MSI). This tool was a little useful in selecting the dll’s and building output, but the SHFB tool is much more user friendly.

Sand Castle won’t fix the out of date documentation problem, but when combined with SHFB it does help when you need to generate something a little more archaic solid than IntelliSense documentation.

Example

Below is an example of compiled help style documentation generated using Sand Castle and SHFB and hana presentation style.

References

Tags: