ITauthor

The internet really is a wonderful thing. How else could I have found out about NDoc? What's NDoc? Well, it's this fabulous tool for turning the XML file produced by Visual Studio from ///-type comments in C# code into professional-looking documentation. I'm in the middle of documenting how to add menu control containing icons to a C# application, using Phil Wright's Magic Libary 1.7 user interface class library for .NET. As part of the page I'm writing (www.itauthor.com/VisualStudio/VisualStudio-Csharp/menucontrols.html), I wanted to include a listing of the simple example program I wrote. There must be something out there that converts C# code to HTML and does it as nicely as perltidy – see my previous entries on this (21 November and 22 November). In fact it took a lot more searching than I thought it would, but my searches eventually led to Jean-Claude Manoli's web site and the C# formatter he wrote "to learn how to use the .NET Framework's regular expressions" (www.manoli.net/csharpformat/). Seems like a lot of work to go to just to learn regexps, but, hey, I'm not complaining because the end result is a cracking good C# code to HTML convertor. Here's an example of what it outputs. My only disappointment about it is that Jean-Claude didn't provide a downloadable application version of the convertor. He did, however, provide his C# source code. The only trouble with that is that you have to know what to do with it and (guess what – I'll try not to get on my high horse here, promise!) he didn't supply any documentation to go with it to tell you what to do with the source. Well, actually, that last sentence isn't true. Jean-Claude has commented his code, so there is documentation. And that brings me to NDoc. Jean-Claude mentions on his site some of the projects he's been working on. One of them is NDoc: an open-source application that makes it easy to "create great looking C# code documentation". That caught my eye, so I followed the link to more information about NDoc and these links to other articles:

• www.squiffler.com/squiffler/article.aspx?id=1
  An article by Ollie Cornes that introduces the topic of using /// comments to produce XML source for documentation. It describes using Visual Studio's inbuilt tool for outputting web page help from the XML and then touches on NDoc. This article is a good starting point. However, it's not been designed to print out in IE (though it prints okay in Mozilla). I've produced a printable version of Ollie's article.
• www.codeproject.com/csharp/CSharpCommentingandDocs.asp
  A short article by Patrick Long, which appears on the very excellent Code Project web site. This covers some of the same ground as the previous article, but more briefly. It gives a bit more detail about NDoc.
• www.ondotnet.com/pub/a/dotnet/2002/12/09/ndoc.html
  This O'Reilly Network article ought to enthuse you to take a look at NDoc. The author, Shawn Van Ness, is a big fan of NDoc and uses it on all his .NET projects. He concludes: "With each new project I work on, I grow continuously more impressed with the flexibility and versatility of NDoc. It's saved me hundreds of hours of tedious labor engineering my own MSDN-style documentation solution, and it looks good doing it!"

Having looked at what it does, I totally agree that NDoc is a must-have application for any .NET developer who's interested in making his/her code accessible to others. There are two very smart things going on here. One of them, of course, is NDoc, which is a very clever bit of work. The best things about it are that a) it's free, and b) it works like a dream. The other smart thing is Microsoft's comments-to-XML-file functionality that makes it all possible. The important thing about so-called self-documenting software is that the end result is only as good as the quality of the comments in the code. Generally (and this is a generalisation) developers are very resistant to the idea of writing in sentences, never mind standard English. To me it seems strange how developers can get the spelling of weirdly named programming commands and functions correct, and they can use the correct syntax, and yet, despite their mastery of a programming language, they often have only a rudimentary grasp of the English language – and I'm talking about English-speaking programmers here. Anyway, NDoc is a great piece of work and I heartily recommend it to you. If you want to try it out, download the source code for Jean-Claude Manoli's C# formatter from www.manoli.net/csharpformat/, then download NDoc from SourceForge (http://ndoc.sourceforge.net/download.html – I chose the web-based .exe downloader for NDoc 1.2). Run the installer. It's a quick install and you don't have to restart the computer. You will probably also want to download the Visual Studio .NET Help Integration Kit from the MSDN web site (if this link doesn't work, go to msdn.microsoft.com/library and search for "VSHIK"). It's is a 6.5MB download, but you need it to produce Miscrosoft Help 2 help from NDoc. (NDoc's default output is MSDN-style help.) Then open Jean-Claude Manoli's C# formatter solution in Visual Studio .NET. Right click on the project in the Solution Explorer and in the left pane of the Property Pages dialog box, click Configuration Properties. Notice that in the Outputs section, there's a property called XML Documentation File. This is set to CSharpFormat.xml. This is the XML documentation file that Visual Studio will produce from the code (including the comment lines beginning ///). Build the project and browse to the project directory in Windows Explorer. Open up CSharpFormat.xml in a web browser. You'll see that Visual Studio has done some clever stuff. It's not just a dump of all the /// lines. Next, start up NDoc (e.g. \NDoc\bin\.net-1.1\NDocGui.exe). Click Add. In the dialog box, use the browse buttons and Open dialog boxes to add \obj\debug\CSharpFormat.dll as the Assembly Filename, and \CSharpFormat.xml as the XML Doc Filename. Click OK. In the NDoc window, click the Namespace Summaries button. Add a description of the Manoli.Utils.CSharpFormat namespace. Click OK. Click the Build Documentation button: On my machine it takes less than 10 seconds to build the documentation for this class library. Click the View button. The finished product looks like this. You can choose to output in other formats (e.g. HTML Help or as web pages) if you prefer. I'd say that was bloody marvellous. Hats off to everybody on the NDoc team!