Coding programs can be a full-time job, leaving little time and energy for developers to document their source code – so why not have another program do it for you? Doxygen is a popular source code documentation tool that can generate an online documentation browser or an offline reference manual from a set of annotated source files. It can parse a range of programming languages – including C, C++, Java, Objective-C, C#, Python, PHP, and VHDL; generate output in a number of formats – including HTML, LaTeX, RTF, and man pages; and works on many platforms, including Windows, Mac OS X, and Linux.
Letting Doxygen generate documentation from annotated code keeps documentation consistent with the source code in a better way than maintaining a separate document. Doxygen is used by many open source projects and even more commercial projects all over the world; it’s localized in more than 30 languages. The largest user bases are in the US, Germany, and Japan, based on download statistics, according to project leader Dimitri van Heesch.
What makes Doxygen unique? Van Heesch says other documentation project alternatives typically handle only a single language or output format or require more markup commands to be useful. Doxygen also provides a structured view of the source code in the form of diagrams and cross-referenced and syntax-highlighted code – even if the code does not have any comments at all. The combination of powerful reverse architecting and documentation capabilities in a single easy-to-use tool makes Doxygen really stand out.
Doxygen began almost 13 years ago after van Heesch graduated from university. At that time the Qt library was in its early stages of development, and van Heesch wrote a table widget as an extension to the library. “The Qt library had beautifully cross-referenced documentation, but my widget had not,” he recalls. “After writing part of the documentation by hand, only to find out that it got out of sync with the code rather quickly, I started looking for a way to automate this.”
Van Heesch asked a Qt developer if there were plans to release that project’s documentation tool. (At the time there weren’t but with the acquisition of Qt by Nokia the tool was recently released as qdoc3.) He found DOC++, which was close to what he wanted, “but the look and capabilities were not good enough in my opinion, and it did not understand the Qt-specific language extensions. So I started coding something myself, taking some of the lexical scanning stuff from DOC++, as that was new to me. I soon realized that this would be useful for others working on Qt widgets as well, so I released it under the GNU Public License. I did not envision I would still work on it 13 years later!
“Doxygen is and has always been my hobby project. It touches quite different aspects of programming and software, and I have full freedom to do what I want, so it is not just more work.”
Although he develops on a MacBook Pro these days, van Heesch says he’s really “a command-line guy.
I always have a terminal or two open, and use all the typical GNU and open source tools, such as ls, sed, make, and gcc. For editing source code I use vim. One of the wonderful tools I miss from my Linux development days is Valgrind; it’s really helpful to find memory leaks, memory corruption, and performance bottlenecks.”
While Doxygen is adept at producing documentation, van Heesch characterizes the project’s own documentation as “rather terse.” Given that, he offers a few tips for users:
– You can extract unannotated code by setting EXTRACT_ALL to YES in the config file.
– Generate diagrams by setting HAVE_DOT to YES and installing the GraphViz package and message sequence charts using Mscgen.
– Try the graphical front end, called Doxywizard, to help configure and run Doxygen.
– You can use the information collected by Doxygen on other tools via Doxygen’s XML output (optionally in combination with the XML parser found in addon/doxmlparser).
– You can split a configuration file into a generic part and overrule certain settings in a specific config file.
Van Heesch has a few enhancements to consider for upcoming versions. “I’ll typically pick one or two that are often requested for a new release. Sometimes I get patches that implement a new features and merge them. Support for Verilog and Ruby are patches that are still in my inbox, for instance. One of the ideas I’m playing with is to enhance Doxygen with a comment system like you see for many blogs, allowing users to add additional documentation to items in a generated page from within the browser. I typically make three to four official releases per year, and each month a tested and tagged Subversion commit.
“I’m always looking for feedback and people to help with the project. I would really welcome a designer who can, for instance, improve the HTML output produced by Doxygen, or a technical writer who’d like to improve the manual. I like to be in control over the consistency and quality of the code, so it works best if people submit patches, which I then review and include. People can contact me directly or via the developer or user mailing lists.”