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. THANK YOU! I’ve been looking all over for a useful C# documentation tool and I never would have thought of Doxygen. It seems to have some issues with partial classes but is otherwise fantastic.

  2. Glad you found this post helpful. Yes, Doxygen does strain a little bit with the C# 2.0 features. C# 3.0 will completely destroy it. 🙂 Hopefully NDoc or some other solution will be up and running by then.

  3. Thanks! I assumed that there must be a means to render the XML files within Visual Studio, and I was just missing it
    (as you say, surely that’s the whole point…)
    Now I know I can give up the search and have a look at doxygen again, after a 4-year gap…

  4. Thanks. It was a perfect suggestion. It Works!!!!

  5. Good and useful narration, thanks.

  6. doxygen with java is also a very nice solution.

  7. Mind you that inline documentation in any .NET language is crucial for the compiled assembly, as it is used when exploring assemblies, either in the Object Browser in Visual Studio, or directly using IntelliSense while typing your code. Hence it’s natural for the compiler to process the documentation as well.

  8. Mike Hoffmann

    Thank you, thank you, thank you!

    I just ported a project to VS2005 (from 2003) and spent an hour feeling too stupid to find the WebDoc generate button. Until I find out it’s gone, for reasons only Microsoft knows.

    Doxygen works like a charm and is just what the doctor ordered!

  9. Glad to help, Mike. Kepp checking the other websites — I do expect Microsoft’s support to improve, and NDoc is bound to be resurrected eventually.

  10. There is a documentation tool for C# programmers called SandCastle…I suggest you download a GUI for it as it comes only with a bunch of .bat files. I found such a GUI which is very similar with NDoc UI called SandCastle Help File Builder.

  11. There are also some commercial applications available that do a really nice job of producing documentation from C# code: Innovasys DocumentX and Doc-to-Help are two tools we have used. Of course, both are expensive, running many hundreds of dollars. We currently use DocumentX at Mini-Tools (www.mini-tools.com) for our .NET components, and it works really well.

    I agree with you that Visual Studio should have included at least a basic version of NDoc or one of the other documentation tools, similar to how it includes a basic profiler and obfuscator.

  12. Thank you for this great post… you sum up the many frustrations of the current state of C# code documentation nicely.

    I wasn’t aware of Doxygen’s C# support, and am quite excited to start putting it to work.

  13. Thank you, thank you, thank you!
    It was a perfect suggestion. It Works!!!!

  14. Nice Generator. I am using VB.Net though. have’nt found anything useful yet. It would be really helpful if someone could poinit me to the right direction.

  15. Thank you so much!!!
    You have no idea how long it took me to find this post…

  16. Thank you, this was really helpfull.

  17. Is there any way I could get a doxygen style HTML documents of the existing c# framework classes.
    I don’t know if they have any of that framework code open. Otherwise I would run doxywizard on it myself.
    If anyone has Any ideas, please mail me @ shobhitgupta12@gmail.com

  18. Well youre telling that in java you have the jdoc, from the begining in .net you got ndoc. The same opensource application but with a .net documentator…

Leave a comment