I've been intending for quite some time to buckle down and learn Doxygen, due both to its usefulness in maintaining large programming projects (which I'm increasingly becoming involved with) and its widespread use within the open source community.

For those of you who aren't familiar with it, the idea behind Doxygen is that you write code documentation in your source code files using a specific format, and then Doxygen will process the source files and automatically generate developer documentation. It's really quite nifty.

So the other day I decided, "Hey, I should learn Doxygen." Of course, being me, I couldn't just go and learn Doxygen with blinders on. No, I had to take a look at the alternatives out there first. And as it so happens, there are quite a few. However, none of them really perked my interest except for one: Natural Docs. Which I will now discuss.

The main difference between Natural Docs and Doxygen is that Natural Docs places a heavy emphasis on making the documentation readable in the source files, not just the generated documentation. That's not to say that the Doxygen syntax is particularly obtuse or anything. It's not. But Natural Docs is just so... natural. It's so intuitive that it's almost scary.

Case in point:

I've spent a fair amount of time honing my coding style to be as readable as possible. One of the things that I do toward that end is write function headers (and method headers, class headers, structure headers, etc.) that are basically mini-manuals for how to use the function. That way you don't have to read through the code to figure out it's precise behavior, and that way it's intended use is made explicit.

Bearing that in mind, let me explain to you a happy coincidence. As I was reading through the user documentation for Natural Docs, I noticed an almost eerie similarity between their syntax and my function header style. It was so similar, in fact, that I decided to run some existing code of mine through Natural Docs unmodified, just to see what happened.

So what happened? It produced usable documentation. I was shocked. It wasn't perfect, mind you—it had some weird stuff here and there—but by and large it was fine. And I didn't have to change any of my code!

So either Natural Docs really is natural, or this is just a really wonderful coincidence. I'm guessing a little of both.

In any case, I have adopted Natural Docs into my list of choice programming tools (right up their with SCons and SVN) and have started using it in my programming projects.

I highly recommend it.

However, it is worth noting that Natural Docs, while more intuitive than Doxygen, is not as robust as Doxygen (yet, anyway). So depending on your project's needs, it may not be the best choice.