Ayende @ Rahien

Refunds available at head office

Creating documentation from XML Comments using Doxygen

I found myself wanting to get some API documentation from a project of mine. Not a particulary odd request, I believe. Unfortantely, it seems that there is little to no support for it from free/open tools. There seems to be a host of commercial tools to do it, but I wasn't about to start going through marketing to evaluate them.

The free/open tools that exists are:

  • NDoc - dead project since august 06, truly sad story. It looks like there hasn't been anything done with it since the lead developer quit, at this point, it is not something that I would like to start using.
  • Sandcatke - from Microsoft, CTP, and according to what I hear, it is truly not ready yet.
  • Natural Docs - I really like the syntax, but it has one issue, it doesn't use the standard XML comments for C#, but rather (a much superior) alternative that is far easier to write. The problem with this is that using XML comments usually means that I can move between tools and (more importantly) that I can get compiler errors if I didn't document a method.

Then I realized that doxygen can produce documentation from C# xml comments. A quick spike later, and I was sold on the idea. Let us take Castle Active Record as an example, it has extensive XML documentation, so it is a good candidate. Here are the steps required to generate documentation from the XML comments:

  • Get DoxyGen and put it somewhere on your hard disk.
  • In the command line, go to Active Record folder and execute the following command:
    doxygen\doxygen.exe -g ar.doxygen
    This will tell doxygen to create an initial configuration file.
  • Edit the ar.doxygen file and add values for:
    • PROJECT_NAME           = "Castle Active Record"
    • PROJECT_NUMBER         = "Release Candidate 1"
    • OUTPUT_DIRECTORY       = docs
    • RECURSIVE              = YES
  • Create a directory called "docs"
  • Now run:
    doxygen\doxygen.exe ar.doxygen
  • Wait until it finishes, and then go to:
    docs\html\annotated.html
    Have fun...

If HTML output is all you want, that is great, but often enough you would like to get a PDF that you can send to the printers, get a stack of paper back and then lobe at unsuspecting people at random (often with calls of RTFM!). At any rate, we need to:

  • Configure the ar.doxygen again, this time adding:
    • PDF_HYPERLINKS         = YES
    • USE_PDFLATEX           = YES
    • LATEX_BATCHMODE        = YES
  • Now go to docs\latex, and you will see a whole bunch of files that I have no idea what to do with. Doxygen will generate a makefile to transform it to pdf, but it doesn't work on windows. We need to do things manually. First, grab MikTex (basic install) and GhostScript and install them, then run the following commands:
    • pdflatex refman.tex
    • makeindex refman.idx
    • pdflatex refman.tex
      Note: if you are getting rerun latex to get cross-references right, rerun pdflatex again.

That should give you a file called refman.pdf, open it up and have fun with it.

I was worried about .NET 2.0 support, but it generated documentation for generic classes without an issue. In fact, check out what it did:

(Image from clipboard).png

I consider this seriously amazing.

Comments

Simone Busoli
02/10/2007 06:26 PM by
Simone Busoli

Thanks for this, doxygen is really pretty.

Arjan Zuidhof
02/11/2007 07:41 PM by
Arjan Zuidhof

I also thought NDoc wouldn't add support for .NET 2.0, so I tried to fiddle with Sandcastle which is a drag - see http://arjansworld.blogspot.com/2007/01/about-10-steps-towards-documenting.html

But have you seen this project called NDoc 2005, an NDoc fork - http://sourceforge.net/projects/ndoc05/ - which has support for VS2005. I haven't tried it out yet, but definitely will one of these days ...

Comments have been closed on this topic.