Doxygen in-body comments

Question

I have some code which I want to document with in-body comments like so:

/*! \file best.cpp
 *  \brief The best
 *
 *  I am the best
 */

/*! \fn void theBestFunction(int)
 * I'm the best blah blah blah
 */
void theBestFunction(int ever)
{
    doThings();
    /*!
     * Does some more things
     */
    doMoreThings();
    /*!
     * Checks that the things it does are the best
     */
    checkBest();
}

But when I run doxygen on this it seems to format the inside blocks into code fragments, as if the @code or \code commands were used (which they were not). I would like the in-body comments to be formatted like normal text.

Has anybody encountered this before? Thanks.

What do you mean @CatPlusPlus? Which part can Doxygen not do? — Andrew Lee, Jun 25 '12 at 16:16
Looks like a duplicate to [http://stackoverflow.com/questions/758045/how-to-be-able-to-extract-comments-from-inside-a-function-in-doxygen](http://stackoverflow.com/questions/758045/how-to-be-able-to-extract-comments-from-inside-a-function-in-doxygen) — ekholm, Jun 25 '12 at 16:16
@ekholm I have seen that question and also http://stackoverflow.com/questions/758045/how-to-be-able-to-extract-comments-from-inside-a-function-in-doxygen but if you read closer it is actually supported (in-body comments). — Andrew Lee, Jun 25 '12 at 16:17
I can't reproduce this. With doxygen 1.8.1 I get that `Does some more things` and the next comment block are rendered as normal text, as expected. What version of Doxygen are you using? — Chris, Jun 25 '12 at 17:35
@Chris 1.8.1.1. Also the output is normal when I only have one in-body comment block. 2 or more and I get that weird code effect. — Andrew Lee, Jun 25 '12 at 17:48
I tried using your complete example code and it rendered fine (as normal text). Seeing as we have the same version of doxygen it seems that there is something missing from the example you give in the question. Can you update your question with a complete minimal example which reproduces the problem you describe (with, if possible, the default configuration file)? — Chris, Jun 25 '12 at 17:58
@Chris Yes, I've updated the minimal configuration in my question. Here is the output I am getting, you can see that the last comment block gets formatted as code. http://imgur.com/G0O9P — Andrew Lee, Jun 25 '12 at 18:48
I still cannot reproduce your problem. Copying your example into an empty file `best.cpp`, running `doxygen -g` and then `doxygen Doxyfile` does not give me the image you link to. The only thing I change in the configuration file is the `INPUT` field (to `best.cpp`). Is there something else missing? Try deleting the output from previous doxygen runs and generating a clean configuration file. Other than that I don't know what to suggest. — Chris, Jun 25 '12 at 20:29
I did what you did and still get the problem. What is the sub-version of Doxygen you are using? Perhaps it is a Doxygen issue. — Andrew Lee, Jun 25 '12 at 20:38
`doxygen --version` just prints `1.8.1`. Can you try a different version of doxygen then? — Chris, Jun 27 '12 at 09:09
So I looked at the documentation of changes between version 1.8.1 and 1.8.1.1 here, and although nothing specifically hinted at the problem, I saw the phrase "Markdown" and "indentation" and I guess that triggered a Eureka moment for me. See my answer. Thanks for your help! — Andrew Lee, Jun 27 '12 at 14:07

score 9 · Accepted Answer · answered Jun 27 '12 at 14:08

I managed to fix the problem. It turns out that somehow Doxygen was processing those blocks as being indented with respect to each other, and indentation in Markdown (much like on StackOverflow) indicates a code block (http://en.wikipedia.org/wiki/Markdown#Code). I simply turned off Markdown and fixed the issue.

For anybody reading this question in the future, if you still want Markdown support, be careful not to start comment blocks on the 2nd line -- start comments right away.

Changing my minimal example to this:

/*! \fn void theBestFunction(int)
 * I'm the best blah blah blah
 */
void theBestFunction(int ever)
{
    doThings();
    /*! Does some more things
     */
    doMoreThings();
    /*! Checks that the things it does are the best
     */
    checkBest();
}

(note the start of the in-body comments immediately, as opposed to a blank line first) solves the issue.

Doxygen in-body comments

1 Answers1