Question

I am trying to include a code example which contains a multi-line comment in Doxygen documentation. The problem is that the C++ preprocessor interprets the */ as the end of my Doxygen comment and therefore the syntax of the file is broken.

For example:

/*! \brief My Doxygen comment.
 *
 * \code
 * myFunction() /* Some multi-line comment */
 * \endcode
 */

I already tried the suggestion which works for JavaDoc comments: encode the slash using HTML entities like this:

* \code
* myFunction() /* Some multi-line comment */
* \endcode

but this doesn’t work (I guess because Doxygen does not replace HTML entities within code sections).

So the question is: is it possible to include multi-line comments in code example and how can it be done?

Answer 1

Use different comment styles.

Instead of what you have, use:

/// \brief My Doxygen comment.
/// 
/// \code
/// myFunction() /* Some multi-line comment */
/// \endcode
///

The /// is the same as /*! and marks a doxygen portion. The pre-processor will treat each line as a single line comment.