Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,026 | Comments: 44,842

filter by tags archive

Creating documentation from XML Comments using Doxygen

time to read 7 min | 1223 words

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:
    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.


Simone Busoli

Thanks for this, doxygen is really pretty.

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 ...

Comment preview

Comments have been closed on this topic.


No future posts left, oh my!


  1. Technical observations from my wife (3):
    13 Nov 2015 - Production issues
  2. Production postmortem (13):
    13 Nov 2015 - The case of the “it is slow on that machine (only)”
  3. Speaking (5):
    09 Nov 2015 - Community talk in Kiev, Ukraine–What does it take to be a good developer
  4. Find the bug (5):
    11 Sep 2015 - The concurrent memory buster
  5. Buffer allocation strategies (3):
    09 Sep 2015 - Bad usage patterns
View all series


Main feed Feed Stats
Comments feed   Comments Feed Stats