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:

I consider this seriously amazing.