Unexpected "code block" formatting for detailed description of enum values using C++ style comments

[ncbrowns]

Describe the bug
In the documentation generated for the source code I'm working on, I am seeing unexpected HTML formatting for the detailed description of enum values that are documented using C++ style comments with a "\brief" description that fits on a single line. This description is unexpectedly formatted as a code block.

Expected behavior
The detailed description of these enums should be formatted as a normal paragraph.

Screenshots

To Reproduce
Here's a sample header that illustrates the problem:

struct S1 {
    /// \brief This is an enum.
    ///
    /// This is a detailed description.
    enum E {

        /// \brief This is a value.
        ///
        /// This is a detailed description.
        VALUE0 = 0,

        /**
         * \brief This is a value.
         *
         * This is a detailed description.
         */
        VALUE1 = 1,

        /// \brief This is a value.

        /// This is a detailed description.
        VALUE2 = 2,

        ///
        /// \brief This is a value.
        ///
        /// This is a detailed description.
        ///
        VALUE3 = 3,

        /// \brief This is a value.
        VALUE4 = 4,

        /// \brief This is a
        /// value.
        ///
        /// This is a detailed description.
        VALUE5 = 5,

        ///
        /// \brief This is a value.
        ///
        /// This is a detailed description.
        VALUE6 = 6,
    };

    /// \brief This is a member.
    ///
    /// This is a detailed description.
    int member;

    /// \brief This is a method.
    ///
    /// This is a detailed description.
    int method();
}

The formatting error occurs with an empty Doxyfile or the default Doxyfile that would be generated via the -g option.

I do not see formatting errors for the S class, the member member, or the method method(), even though they are all identical. I also don't see this error for C-style comments (VALUE1), if the brief and detailed description are separated by blank lines instead of an empty comment (VALUE2), if the is an extra comment-only line before \brief (VALUE3 and VALUE6), or if the \brief description spans two lines.

Version
This was originally observed on Doxygen 1.9.3, but it also reproduces on Doxygen 1.10.0, both on Windows.

Stack trace
N/A

Additional context
I can't think of anything else relevant here.

[ncbrowns]

One other thing I forgot to add. When trying to work around this issue, I did one experiment where I added \details to the detailed description. It did not work and \details was treated as part of the code block. To observe this, add the following to my example immediately below the definition of VALUE6.

        /// \brief This is a value.
        ///
        /// \details This is a detailed description.
        VALUE7 = 7,

[ncbrowns]

One other interesting detail I just discovered while attempting to work around this issue in my real project. The header where I was seeing the errors is generated from a script. My initial attempt at working around the problem by adding extra lines before and after the enum description (as in VALUE3) incorrectly indented the extra comment lines. That experiment did not fix the formatting problem. This can be seen in the following extra test case:

      ///
        /// \brief This is a value.
        ///
        /// This is a detailed description.
      ///
        VALUE8 = 8,

where "This is a detailed description" is formatted as a code block.

[albert-github]

I didn't look deep into the problem yet but it looks like there is the "4 space" markdown rule playing a role here, i.e. when a line is indented with 4 extra spaces compared to the previous it will be seen as a code block.
I also looked with the debug option running doxygen -d commentcnv and the result looks quite OK, so it looks like the markdown processing has a small counting problem.

That said it might be important that the exact use case as mentioned in the issue and comments is presented (as otherwise the editor or cut / paste utility might play a mean role, so:

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).

[albert-github]

Especially the converted difference between the VALUE0 and VALUE6 gives a nice clue:

        /** \brief This is a value.
         *
         *  This is a detailed description. */
        VALUE0 = 0,

and

        /**
         *  \brief This is a value.
         *
         *  This is a detailed description. */
        VALUE6 = 6,

i.e. the fact that in the VALUE0 case the description directly follows the /** and in the VALUE6 case it is at the next line.

We have to be careful here as just changing:

        /** \brief This is a value.

into

        /**
         *  \brief This is a value.

will give problems with correct line numbers in case of warnings etc.
(and also when originally formulating the comment block with /** \brief... will still show the problem).

[ncbrowns]

Attaching a full repro package, including a Doxyfile generated from Doxygen 1.10.0 on Windows using "-g":

doxytest.zip

My main test case is header1.h. To be sure that Unix vs. Windows line endings couldn't explain the problem, I cloned that file into header2.h, renamed the class to S2, and converted the file to have Unix line endings. The documentation generated for S2 shows the same problem.

I hope this is helpful.

[albert-github]

I've just pushed a proposed patch, pull request #10633

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.11.0.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).