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.

Answer 1

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.