More cool software: Doxygen

Since I teach my students to document their code well, and since I've had long experience of not being able to make heads or tails of my own code after more than a couple days, I've been working on making my own code's documentation more useful. I had been using Apple's HeaderDoc software,

which converts JavaDoc-like comments in code to HTML. It's a bit clunky, but OK. Then, I tried Doxygen, a truly incredible package. First off, it will do almost everything without special markup: UML class diagrams, class hierarchies, call graphs, header include dependency graphs, cross references to called functions, etc. So you can use it to extract code structure to reverse engineer and reuse undocumented source files. Using the Graphviz package, it generates beautiful graphs. If you have comments before each class, method, and variable, all that will automatically get included in the generated documentation. If the comments were to include, for example, XML, it will detect that XML's structure and format it with appropriate indentation. You can also include a wide range of Doxygen-specific markup to create explicit links, file dates and versions, numbered or bulleted lists, mathematical formulas, etc. And, while I'm using it for C++, it works for many different input languages.

Note that I haven't mentioned output format. That's because Doxygen will output just about anything you'd want: HTML (with and without frames), LATEX, RTF (for MS Word), Postscript, PDF (with hyperlinks), compressed HTML (for Windows Help), and Unix man pages. The original source code can be included with the documentation, which means the HTML output is really an absolutely complete documentation web site for the project. The output can be completely customized to "brand" the documentation as you like. The only downside I see is that you must rebuild all of the documentation, rather than just the documentation for a changed file (probably unavoidable, given that the software automatically determines and documents interdependencies). If you write code, I think you'll agree that Doxygen will make your work look good.

[+/-] show/hide the rest of this post