doxygen for lazies

TL;DR: to get doxygen docs really fast you can run the doxify script as:

$ doxify path-to-project path-to-docs
# Done!
$ firefox path-to-docs/index.html

Let’s do the same for a small yet complex real-world C++ project: re2c.

The session looks like:

$ git clone https://github.com/skvadrik/re2c
$ doxify re2c/re2c/src re2c_docs
warning: Output language Russian not supported! Using English instead.
warning: failed to open layout file 'DoxygenLayout.xml' for reading!
warning: Included by graph for 'c99_stdint.h' not generated, too many nodes. Consider increasing DOT_GRAPH_MAX_NODES.
$ firefox re2c_docs/index.html

The docs generation process takes 9 seconds on my machive. I’ve uploaded result here. I won’t update that documentation thus it’s frost in time.

By default doxygen generates documentation only for explicitly documented files and functions thus we override that behaviour and force it to tell us everything it knows about the project. The following doxify line is responsible for it:

doxygen_set_value "EXTRACT_ALL" "YES"

Most of the rest is a nicety to get a code browser inline with documentation.

Let’s look at actually generated stuff. There is:

• Namespaces
• Classes
• Files

Under Classes there is Class Hierarchy dropdown. Some complex projects have huge class hierachies. One click and you know re2c is not one of them :)

Under Files we can find a lot of useful info as well. Picking main.cc as an example:

• Transitive header inclusion graph. If you click on a header you’ll get both direct and reverse inclusion graphs: input_api.h
• Highlighted function definition with clickable cross-references: main() funcion
• Original source code with highlight fancy and cross-reference links: main() again

More random examples:

• re2c::Output
• clicking at the legend under any graph will decipher arrow colors
• ~Output() destructor has a nice callgraph
• re2c::matches does not call anyone but is called occasionally: its reverse callgraph

Have fun!