Search code examples
documentationdoxygen

Doxygen lists within exception tags render incorrectly

A list in the main doc of a symbol...

/**
 * - foo
 * - bar
 * - wah
 */

renders nicely in Doxygen as bullet points:

enter image description here

The Doxygen documentation for the exception tag includes:

The text of the paragraph [after @exception] has no special internal structure. All visual enhancement commands may be used inside the paragraph. Each exception description will start on a new line. The \exception description ends when a blank line or some other sectioning command is encountered.

Despite that "all visual enhancement commands may be used inside the paragraph", it seems that lists cannot render correctly inside exception tags, possibly due to the strict handling of line ends.

The same list, inside an exception tag...

/**
 * @exception myError
 * - foo 
 * - bar 
 * - wah
 */

renders as bullet points strangely spaced apart:

enter image description here

It is possible Doxygen interprets each element of the list as a separate "exception description", and as such, separates them by newlines. How can I avoid this behaviour, such that lists render as bullet points in the same way they do in the main doc?

I'm using Doxygen 1.8.13 on Ubuntu 18.04. Here is my doxygen config file which renders the below MWE incorrectly:

/**
 * - foo 
 * - bar 
 * - wah
 * @exception myError
 * - foo 
 * - bar 
 * - wah
 */
void myFunc();
Solution

  • Doxygen 1.8.13 is already a bit older (December 2016), I certainly advise to update to the current version 1.9.1 but this is not the cause of the problem/.

    The provided Doxyfile is not really minimal and contains a lot of project specific stuff not relevant for the issue at hand. A doxyfile with

    EXTRACT_ALL=YES
QUIET=YES

    is sufficient.

    When running the given input we get:

    enter image description here

    The question is where do we want to have the word Exceptions and the subsequent list items? Currently the first set of list items is not terminated till after the second - wuh and the Exceptions is seen as part of the first wuh list item and the second foo is seen as a level 1 list item hence the above shown output.

    A solution (not the extra space before the items after the @exception making it here a second level list):

    /**
 * - foo
 * - bar
 * - wah
 * @exception myError
 *   - foo
 *   - bar
 *   - wah
 */
void myFunc();

    result:

    enter image description here

    Probably the wanted solution (note the empty line before @exception which terminates the first list):

    /**
 * - foo
 * - bar
 * - wah
 *
 * @exception myError
 * - foo
 * - bar
 * - wah
 */
void myFunc();
~

    result:

    enter image description here

    (I ran everything with the 1.8.13 version)