C# documentation comments: useless?

Despite C# being several years old, there’s no official supported tool for generating human-readable documentation from C# programs. Microsoft’s C# specification describes a rather verbose form of documentation comment that programmers are supposed to use in their code, but they don’t supply the tools to do anything useful with these comments. After a bit of searching and quite a few dead ends, I finally found a simple way of generating the documenttion I needed. Here’s the full story.

The documentation comments in C# code aren’t ignored entirely by the Microsoft C# tools. The C# compiler usefully checks the documentation comments for consistency with code, although it does seem strange for a language compiler to be looking at comments. If the correct command-line option is used, the compiler will also copy the documentation comments to an XML Documentation file, which will thus contain all the documentation comments for all files in the project. However, the XML file is useless as it stands. Recommended Tags for Documentation Comments on MSDN says, “Processing the XML file to create documentation is a detail that needs to be implemented at your site.” They call it a “detail”; I would call it the whole purpose of having these doc comments in the first place.

Compare this with the Java world, where Javadoc has been there since the beginning (more or less). Javadoc can generate documentation directly from source code (incorporating documentation comments) or object code (without comments). Documentation processing is done entirely by the Javadoc tool; the Java compiler ignores comments, as it should (they are called “comments” after all).

To produce usable documentation from C# documentation comments, a “documentation generator” is required to combine the object code (assembly) and the XML file into human-readable form. So the processing of documentation comments is divided between the compiler and the documentation generator, and the code must be compiled in order to produce documentation. This seems to mean that it would not be possible to produce documentation for an incomplete source hierarchy, though I haven’t tested this.

So, we need a documentation generator. There’s lots of information in various places about the very useful “Code comment web reports” function in Visual Studio .Net (e.g. Creating Code Reports on MSDN). Sadly, one fact that is not documented is that this feature is no longer in VS 2005.

There is also a lot of information about the open-source NDoc tool too. Sadly, a little bit of digging reveals that it does not support .Net 2.0 and it is no longer being actively developed. The original developer has left the project, and while it has been handed over to a new team, no new development has yet surfaced. There are unofficial efforts to support .Net 2.0, such as Jonas Lagerblad’s NDoc for .Net 2.0, but they look a bit unfinished.

Just a few days ago, Microsoft released the first public version of a documentation generator that they use internally. Sandcastle is not (yet) an officially supported product, and the version available now is a pre-release. It’s not at all easy to set up and use, but I did manage to get it to work with the help of an MSBuild script for Sandcastle from Anders Ljusberg. Sandcastle ground away for ten minutes before producing the documentation for the class libraries used by my web application.

The output of Sandcastle is a Microsoft compiled HTML (CHM) file. This shows a tree view of namespaces, which contain classes, which contain members. Each has all the basic stuff you would expect — comments, cross-references to other types, and syntax-highlighted method signatures (in your choice of C#, Visual Basic or Managed C++). Unfortunately, there’s no overall view, like class or inheritance diagrams.

Sandcastle goes by the book, and produces its input by combining the XML Documentation file (for the comments) and the compiled code assemblies (for all other input). Producing the assemblies is no problem, but it turns out to be a real pain to generate the XML Documentation file for Visual Studio 2005 Web site projects. This is a real shame if you’re trying to generate documentation for a web site, as I was. It turns out that this is a new VS 2005 feature. The new Web site project type is a streamlined version of the old Web application project type, and one of the dropped features was the simple one-click XML Documentation file generation.

I found a few workaround solutions for this problem. The best seemed to be to install an add-in to Visual Studio 2005 that allows a Web site project to be converted to a Web application. This turned out to be a bit of a rigmarole. First I had to install a Visual Studio Update to Support Web Application Projects. I installed it — the progress indicator counted down the number of seconds remaining until it reached zero, and then I sat there looking at “Time remaining: 0 seconds” for about 15 minutes before it finally told me that the update had been installed. Amusingly, I then got another progress indicator showing “Time remaining: 8 seconds” for about half a minute before the installation actually finished. I expected the worst when I was finally able to install the actual Web Application Projects add-in, but it only took a minute or so.

After all that, I never even used the add-in, because in the time it took to install all this, I discovered a much better solution. Doxygen was originally a C++ documentation generator using the same sort of approach as Javadoc, except it works only on source files. I remember being quite impressed by Doxygen when I used it on a large C++ project a few years ago — the document comment style it supported was much more elegant and concise than Javadoc comments (and C# documentation comments, which are even worse). So imagine my joy when I discovered that Doxygen now supports C#, including C# style documentation comments.

I downloaded Doxygen and ran the Doxywizard GUI, and within five minutes had complete documentation for my class libraries and website. And when I say complete, I mean all the basics, plus class inheritance graphs, collaboration diagrams, and cross-references to syntax-highlighted source code. Doxygen does this by ignoring any XML Documentation files, and simply getting all its information directly from the source files — a much better idea.

It’s true that Doxygen’s C++ roots run deep; I don’t know how well it handles C# features like anonymous methods, delegates, events and nullable types. But certainly it has some very impressive features, and amply fulfils my needs. It still seems quite strange to me that Microsoft don’t have any support for generating proper documentation at all, let alone integrated into their IDE; but until they do (or NDoc 2.0 appears), Doxygen will do it for me.