C# documentation comments: useless?

Sunday, 6 August 2006

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.

Tags: ,

38 comments

You can leave a comment, or trackback from your own site.

  1. Whoa, doxygen is really download, install and voilà. But I don’t give up with Sandcastle yet, maybe there is some frontend that works, even with VS 2008…
    Microsoft really screwed up badly here ;-(

  2. I want to document an XML file.Is there any tool/software available which can document an xml file

  3. Aralmo: Agreed. But Ndoc worked fine with framework 1.0 ( and 1.1 I believe ) but since 2.0 there is no support for it ( for a good personal reason of the owner ).

    AA: THATS an option that is built-in. Just go to visual studio and use the option :). But I figured that you dont use VS because else you would know that .. right ?

  4. Gggggrreeeaatt ppooosstt.. Thank you ssoooo mmmuuucchh.. I am going to give it a try.. do you have other better solutions, because it has been 2 years since your post regarding doxygen ?

  5. Thank you! Best post of the internet!

  6. Dude, you rock! Doxygen is major sweet and easy. It takes a little to get the graphs to work; make sure you install graphviz 1st and make sure you point the config file to its path location. Other than that, I dig it.

    Thanks again!

  7. You don’t need to point Doxygen to graphviz provided graphviz binaries are on your path. Yes, it rocks!

  8. I think you’ve missed one of the best points of the Xml comments which is the tight integration with the IDE.

    When you use a Class, Property or Method (from code) it will display the information contained within the Xml comment as a tooltip annotation to help you whilst you code. This is especially useful for method calls, as it will show you the comment for each parameter being passed to the method. This is cool because when a method has been commented correctly you know the purpose of each parameter as you type the code.

    This also works when you distribute your code as a DLL, it will retain the comment documentation (unless you tell the compiler not to).

    This all makes well doc-commented code super easy to use. The reason the compiler needs to know about the comments is so it can link them to their associated Class/Property/Method. This is not a bad thing, infact it’s super useful.

    Matt

  9. Thanks a lot for the post. It save me so much time!!!
    great work!!!

  10. I found the holy grail: Sandcastle Help File Builder.
    http://shfb.codeplex.com/
    This tool is outstanding.

  11. @geac, thanks for the pointer. I hoped that Sandcastle would eventually become useful — great to see it’s being actively maintained.

  12. Rupert Barclay

    If you are willing to pay for a commercial tool you should take a look at Innovasys Document! X – we’ve been using it for some time and apparently it’s the tool also used by Infragistics and some other brand name .NET component ISVs to do their commercial docs which is a good sign. It’s an authoring tool as well as a documentation build tool – includes a Visual Comment Editor in VS as well as external authoring that our tech writers use. We also use it for database and XSD Schema docs (and I believe it does some other stuff too that we haven’t used).

  13. First of all I want to say terrific blog! I had a quick question that I’d like to ask if you do not mind.
    I was curious to find out how you center yourself
    and clear your head before writing. I have had trouble clearing my mind in getting my
    ideas out. I do enjoy writing but it just seems like the first 10 to 15 minutes tend
    to be lost just trying to figure out how to begin. Any
    suggestions or tips? Thank you!

Leave a comment