Blue GNU interviews Dimitri van Heesch, founder and maintainer of the Doxygen project, to learn more about about how developers can manage their documentation.

First, would you mind telling me a little about yourself, Where you live and your interests?

I'm the creator and lead developer of Doxygen, a popular source code documentation tool. I'm from the Netherlands, and am 33 years old. I've been programming since I was 12 and later also obtained a Master's degree in computer science. In my professional life I have been a researcher and engineer in the area of
embedded system's software in general, and video processing in particular.

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.

Other hobbies include building robots and watching movies.

When and why was Doxygen started?

Doxygen started a little over 10 years ago. I just finished my graduation project at the University and was looking for a job. I don't remember why exactly, but I wrote a table widget as an extension to the Qt library, which was then still in its early stages of development. Although not maintained anymore, the table widget is still available from SourceForge. The Qt library had beautifully cross-referenced documentation, but my widget had not. After writing part of it by hand, only to find out that the documentation got out of sync with the code rather quickly, I started looking for a way to automate this.

The Qt library also used some kind of documentation tool, since it had comments with all kinds of markup commands embedded in the code. I first asked a Qt developer if there were plans to release it. The answer was a clear no. So I decided to work on my own tool for documenting my widget such that it would nicely blend in with the Qt documentation.

I did look around on the web first and found DOC++, which was similar to what I 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. That's how Doxygen was born. Already at the first release -- encouraged by positive feedback -- I was determined to make a mature tool that would be better than anything out there, but I
had not envisioned I would still work on it 10 years later!

Where does the project stand at this point?

The project is mature and stable. Nevertheless, the first couple of hours after a new release are always quite exciting to see if it is not a "brown bag" release, but usually there are few problems.

Although Doxygen works well in general, there is of course always room for improvement. There is a huge "todo" list with things people would like to see added to Doxygen.

Despite being mature and stable, Doxygen is also actively being worked on, which can be conflicting at times.
Since there is a lot of code documented with doxygen already, it is very important to keep the tool backward compatible.

How many active developers currently work on Doxygen?

I am the only long term all-round developer. There are people helping me with the subversion repository,
and with the translation of the builtin sentences into various languages (over 30 currently). People have contributed extensions such as Python, Fortran, RTF, and HTML help support on an ad-hoc basis. Whenever I receive a patch, I merge into Doxygen's mainline if I think it useful for others.

What is your primary development toolset?

Although I do my development on a Macbook Pro these days (which was kindly donated by Apple), I'm really a command line guy. So I always have a terminal or two open, and use all the typical GNU and open-source tools like ls, sed, make, and gcc. For editing source code I use vim. Before I had my Macbook, I developed on Linux (I've used Slackware, SuSE, Gentoo, Ubuntu, and Fedora over the years). One of the wonderful tools I miss on my Mac is valgrind; really helpful to find memory leaks and memory corruption.

Many projects depend on libraries, tools, etc. developed by others. What are some of the key external elements you rely on?

I try not to rely on other libraries if possible, as these tend to change over time and since there are so many users with different environments, it quickly becomes impossible to make Doxygen work in all situations. The libraries I do use are bundled with Doxygen. They are: libmd5, libpng, libz, libiconv, and the tools directory of (an old version of) Qt.

Other tools that Doxygen can use optionally are:

dot

to render various graphs (part of the GraphViz package)

mscgen

a tool to generate message sequence charts

latex

as an intermediate step to generate PDF documents and to render formulas

ghostscript

to turn formulas into pictures that can be embedded in the HTML output.

html help workshop

on Windows only to compile a .chm file from the HTML output.

How does Doxygen compare (in your view) to other projects?

There are quite a number of other documentation projects like Doxygen (I even keep a list on my web site).
Typically they are less generic (only for a single language or output format) or require more markup commands
to be useful. Doxygen also provides a structured view on the source code -- in the form of various 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 tool, which is still
easy to use, is what makes Doxygen quite unique in my opinion.

With respect to other projects in general I think Doxygen benefits from the fact that most users are also software developers. This helps with the quality of bug reports and patches, which are quite good compared to other projects.

Can you give me any idea of how big and/or active the Doxygen user community is?

It is used by hundreds of open source projects and probably even more closed source projects, ranging from small helper libraries to huge ones such as KDE, and from smart phone software to mission critical software such as for the new Mars rover made by Nasa's Jet Propulsion Lab.

To give a idea about the popularity. The tool is downloaded approximately 15,000 times a month. If the announcement mailing list is any indication of the number of users then there are more then 17,000 already.

What needs to be accomplished before the next release of Doxygen?

If regressions have been found I typically try to fix them in a new release. Other than that I do not plan work in advance too much. It is more that I release a new version periodically when a number of bugs has been fixed. Part of my time I work on new things as well. For people that want to try new features early or get blocked on a bug that has been solved, I also commit intermediate versions to subversion. Typically there are 3-5 intermediate updates between two official releases.

One of the ideas I'm currently playing with is combining the functionality of Doxygen with that of a wiki, i.e. allowing users to add comments to already deployed pages. This is common for blogs and news sites these days, so why not add it to doxygen as well? If it turns out to be useful and feasible this could end up in a next release.

What are the biggest obstacles the Doxygen team faces in development?

Lack of time is by far the biggest obstacle. One solution for this would be to open up the repository to multiple developers. Even if these developers could be found, I hesitate to do this because Doxygen is not yet as modular as it should be, so it is difficult to split up the work without treading on each others toes. I also find it difficult to guarantee a certain level of quality and consistency if I do not review and understand all the code.

Feature creep is another problem. Since there are so many users all with their own preferences, Doxygen has
gathered a lot of diversity settings, making testing of all combinations impossible. As a result it is difficult to change something (for instance an internal redesign) without breaking something in a certain configuration. I try to be very restrictive when it comes to adding new configuration options; nevertheless there are no less than 180 options at the moment.

Is there anything else about Doxygen you think our audience should know?

I'm always looking for feedback and people to help. You do not even have to write code to help. I would really welcome a designer who can for instance improve the html output produced by Doxygen, or a technical writer who likes to improve the manual.