Failing Forward

I’m going to start a small series on applications (or generic types of applications) that every developer should (read: really, really, really should) be using. Now of course I’m going to be able to give examples and recommendations for only the brands that I use. My goal is to introduce new types of software to those who have never used them, and not to wage a religious war bickering about which implementation of the technology is “best.”

Today, we look at automatic documentation software. What’s that… a program that writes your comments for you? Hardly. But what documentation generation software WILL do, is take the comments you write in your code, and coerce them into a more user-friendly format, usually within an html environment. And, if you pick the right software, it can do a whole lot more for you.

A lot of developers tend to think of documentation simply as the comments throughout their code.

/* This is a C-style
* block
*comment
*/
# This is a shell script comment
// This is a PHP-style comment

And of course there are more. This is nice for the casual developer, personal projects, and the like. But for really large projects, for hard-core open source stuff, or for professional software, there’s something missing here. What if you’re on a team, and you want your team to know how to use an API you wrote, without worrying them with the specifics of it’s implementation? What if you just want a professional looking interface to your latest and greatest API? Perhaps you’d just like something to throw online to prove to others “Hey, I am actually working on this” without blindly tossing source code onto the interwebs. This is where documentation generation comes into play.

I’ve got experience with Doxygen. Great open source project. For Doxygen (and it’s the same with others, such as phpDocumenter and Javadoc), all you need to do is format your comments the proper way. For a block-style comment, use the form:

/** This is a bloc comment. */

or

/** This is a
* block comment.
*/

Inline comments (C++-style) go like this…

/// This is a line comment, and applies to the code below it.
<This is some code>

And this

<This is some code> ///< This comment applies to the code preceding it.

That’s it. That’s all you have to do, and Doxygen will create documentation for you in a slew of forms, including html, xml, latex, rtf, postscript, pdf, and even Unix man page format. Here‘s an example of Doxygen’s output. Note that all the developers of that code had to do, was to follow the commenting convention set by Doxygen. Doxygen was responsible for chewing through all of the code, writing the HTML, styles, diagrams, links, lists, tabs… everything!

Doxygen supports “C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D” according to it’s website. Now like I said at the beginning, which documentation generator you use is your choice, but I’d HIGHLY recommend trying one/some out then actually using it/them. Doxygen is also capable (alongside graphviz’s dot tool) of creating images that depict call graphs, dependency trees, and the like.