dox++

dox++ is a Clang-based documentation preparation system for C++.

Examples

• These pages are generated using dox++ (although we’re not documenting a C++ project), and use the default light theme.

• There’s the documentation for an example project generated by dox++, and using the default dark theme.

• The DIPlib documentation is generated by dox++, using customized CSS.

Justification

Doxygen is the de-facto standard documentation system for C++. Its HTML output is not flexible enough for many people, who resort to using the XML output and parsing that into their own HTML. However, Doxygen’s XML output has some issues and does not contain all information present in the HTML output. For example, when using groups (“modules”), the XML output does not have links for types documented in other groups. Doxygen also often requires weird and frustrating workarounds where its Markdown parsing is incorrect.

There are several Doxygen alternatives, but none seemed suitable for my purposes.

dox++ is yet another alternative, meant to be simple in implementation rather than feature complete. It depends on Clang to parse the C++ header files. It does the things I need it to do, but it might be lacking in areas that are relevant to you. I invite you to improve on it and send a pull request. The project focus is C++ code, not C code, and so some C features might be overlooked on purpose.

dox++ follows the Doxygen syntax only partially. Most projects will require at least a little bit of work to port over. See Differences with Doxygen.

Components

dox++parse produces a single JSON output for the whole project. This JSON file contains all the information needed to produce documentation. It contains documentation for all namespaces, classes, functions, variables, etc., even those without explicit documentation blocks. It contains documentation for each header file and for each group, and it contains additional pages. It links references to members across the project. Typesetting, creating indices, etc. is left to the generator, which keeps the program simple. This is equivalent to running Doxygen with XML output, with the intention of using a 3rd party tool to turn that XML into user-browsable content. Do however note the Differences with Doxygen.

dox++html produces a series of HTML files documenting the project, using the JSON created by dox++parse. The generated HTML is based on m.css, and its fantastic Doxygen C++ theme, by Vladimír Vondruš. It is all static HTML5 with customizable CSS, and wonderful client-side search functionality that uses JavaScript. The output has some differences with m.css, see Differences with m.css.

Other generators are considered.

See the Documentation to learn how to use these tools.

What is missing

I’m sure there are lots of things missing I’m not even aware of. Here are a few missing things that I am aware of:

1. Template parameters that are templated types are treated a bit too simplistically. It would be nice to turn referenced members here into links.

2. Link override and overridden functions together.

3. There’s no way to have the literal text “\‍ref” (and similar commands) in the documentation, we need to avoid matching commands inside backticks or in code blocks (we’re inserting the non-breaking zero-width word joiner U+200D after the backslash to show you this command in these pages).

4. References to a member that is injected into a different namespace it was declared in are not resolved (e.g. through a using statement, or members of an anonymous or inline namespace).

5. Anonymous unions are not yet recognized.

6. Clang doesn’t easily report on pre-processor macros. Instead of making things complicated, we just require adding the \macro (or \def) command at the top of the documentation block.

7. Function arguments can not yet be individually documented. \param, \return and \exception are not yet supported.

8. We cannot yet include source code from another file, or create pages for example programs.