Menu
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.
339
Doxygen comment blocks are easy to create. For line comment just insert a triple forward slash. /////This line will be included in the Doxygen comments for this function/class/file
Click here for the corresponding HTML documentation that is generated by doxygen. For the brief description there are also several possibilities: One could use the \brief command with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line. /*! \brief Brief description.
@class This tag informs doxygen that the comment block should be associated with the class. This block should explain the purpose of the class, the design considerations, and relation to other classes. Also provide any information other programmers may find useful for using the classes.
As you can see doxygen is quite flexible. If you have multiple detailed descriptions, like in the following example: //! Brief description, which is //! really a detailed description since it spans multiple lines. /*! Another detailed description!
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.
122
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With