Differences with Doxygen

dox++parse follows Doxygen syntax only partially. Here we highlight the more important differences. See the Documentation for more details.

Changes from Doxygen are as follows:

  1. Markup commands are passed as-is into the output JSON file, and left to the generator to parse. Our current generator does not parse any of the Doxygen markup commands, and assumes pure Markdown (which accepts HTML tags as well). Markdown formatting works also in page and section titles.

  2. Documented members can belong to one group (module) at most. Groups form a tree structure. Grouping commands have the same names but work slightly differently (plus \group is an alias for \defgroup). We don’t recognize \{ and \}; instead, use \addtogroup and \endgroup (see How grouping differs from Doxygen). \weakgroup is not recognized either. Namespace and class pages link back to the group they belong to, if applicable.

  3. It is meant to parse header files only, not the implementation files. It documents the API of a library, not all the code in a project. It documents everything declared in the header files, even if no documentation block is associated to the declaration. The generator can choose what to output. Directories are not documented, only the header files themselves.

  4. Commands intended to document members cannot define non-existing members. For example, the \class <name> command adds documentation to a class. The class must be declared somewhere in the header files. These comment blocks cannot define properties of the documented members, those properties must be reflected in the code itself. For example, \extends, \pure or \static are not recognized. Some of those commands have simpler interfaces: \fn, \var or \typedef don’t take a declaration, only a name. Some commands have aliases that make more sense (for example \macro for \def, \alias for \typedef, \function for \fn).

  5. Markdown files can contain comments with the \comment command. There is no empty page generated for Markdown files that contain member documentation.

  6. Unique identifiers for members are fairly readable, and don’t look like the hashes that Doxygen generates. This should allow the generator to create more meaningful URLs.

  7. SFINAE template parameters are summarized as “<SFINAE>“. Multiple definitions of a template with different SFINAE results (such as when one version is defined for unsigned numeric types and another one for signed numeric types) are collapsed into a single (documented) template.

  8. There is no “autolink”, all links must be explicitly made with \‍ref. Consequently, it is not necessary to prepend % to avoid turning some words into links. \‍ref is used to link to anything in the documentation, not just pages and sections. \link and \endlink are not recognized.

  9. dox++html creates pages for undocumented classes, namespaces and files that have documented members. Thus, it is not necessary to document a file just to be able to document the functions that are declared in it.

  10. With Doxygen there’s sometimes a need for conditional compilation to avoid getting its parser confused. Because dox++parse uses Clang, there’s no danger of confusion.

  11. \param, \tparam, \returns and the like are not yet supported. Currently function arguments must be documented in the documentation text.