Code Yarns ‍👨‍💻
Tech BlogPersonal Blog

How to use Doxygen to generate documentation

📅 2010-Oct-26 ⬩ ✍️ Ashwin Nanjappa ⬩ 📚 Archive

Doxygen is a useful tool to automatically generate documentation for code. It can produce beautiful documentation if the code comments are written in its custom format. Thankfully, even if this is not the case it can still produce documentation that can be useful for understanding a mass (or mess) of code.

Doxygen uses a configuration file, typically named Doxyfile, to generate documentation. Linux users might like to set their configuration in this file. Doxygen also ships with a GUI tool named Doxywizard that makes it easy to create a configuration file and generate documentation for the first time. Windows users might find it easier to use this tool.

Using Doxywizard

As an example, assume the code in a project has the following directory structure:

C:
+---Foobar
    +---Code
    +---Docs

That is the project root directory is C:\Foobar, source code directory is C:\Foobar\Code and the documentation produced by Doxygen will reside in C:\Foobar\Docs.

To produce this, fill the fields in Doxywizard as follows:

 

In the Run tab choose Run Doxygen to generate the documentation. It will be produced in the format you chose: HTML, CHM, XML, RTF or many others.

It is a good idea to save the configuration to a file named Doxyfile in the project directory. Do this in the Doxywizard by choosing File → Save As. By having a configuration file around, the documentation can be updated whenever the code in the project changes. This can be done directly by invoking doxygen.exe in that directory or can be automatically invoked by your build tool.

Using doxygen

The doxygen program can be used to generate a sample configuration file named Doxyfile for you:

$ doxygen -g

If you open this file, you will find that it has all the options understood by the version of doxygen on your computer. These options are excellently documented making it easy to configure them.

However, the hundreds of options in this file can be quite intimidating. I typically configure these options to start off:

To generate documentation:

$ doxygen

To get started quickly, I have shared my Doxyfile for C++ and CUDA code here. Just look for foobar in the file and replace with your project name and directories.