Search results

Doxygen, a document generator mainly for C++

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

An alternative to Javadoc is Doxygen. Doxygen works highly similarly to Javadoc, except that it can process more languages (Java, C++, C#, and more). Doxygen is most commonly used with C++. Additionally, there’s a GUI tool called Doxywizard that makes it easy to generate the file.

Download Doxywizard

The Doxygen download also includes Doxywizard. See the Doxygen Downloads page for more download links.

Here’s the Doxywizard front-end GUI generator:

Doxygen front-end GUI generator
Doxygen front-end GUI generator

Here’s the Doxygen output:

Doxygen Sample
Doxygen Sample

You don’t need to use the wizard. You can also generate Doxygen through a configuration file, which is typically how developers run Doxygen builds from a server.

In contrast to Javadoc, Doxygen also allows you to incorporate external files written in Markdown. And Doxygen provides a search feature. These are two features that Javadoc lacks.

Doxygen is maintained by a single developer and, like Javadoc, hasn’t changed much over the years. In my opinion, the interface is highly dated and somewhat confusing. But C++ developers will be accustomed to it.

Integrating builds automatically

In a lot of developer shops, document generators are integrated into the software build process automatically. Doxygen allows you to create a configuration file that can be run from the command line (rather than using the frontend GUI). This means when developers build the software, the reference documentation is automatically built and included in the output.

Other document generators

You don’t need to limit yourself to either Javadoc or Doxygen. There are dozens of different document generators for a variety of languages. Just search for “document generator + {programming language}” and you’ll find plenty. However, don’t get very excited about this genre of tools. Document generators are somewhat old, produce static front-ends that look dated, are often written by engineers for other engineers, and not very flexible.

Perhaps the biggest frustration of document generators is that you can’t integrate the rest of your documentation with them. You’re mostly stuck with the reference doc output. You’ll also need to generate your how-to guides and other tutorials, and then link to the reference doc output. As such, you won’t end up with a single integrated experience of documentation. Additionally, it will be hard to create links inline within topics between the two outputs. Fragmentation of outputs is a topic I explore with more detail in Integrating Swagger UI with the rest of your docs.

132% Complete

132/146 pages complete. Only 14 more pages to go.


Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.