How can I show a comment block inside a code block inside a doxygen block?

user_309425 0
Viewed 94

Let's say I want to show a /* - */ delimited comment block inside a code block in a Doxygen documentation block in C++ code. If the Doxygen block, is itself /* - */ delimited, like this,

/**
    documentation
    \code
    /*
        comment 
    */
    \endcode
*/

that's clearly going to be a problem: Doxygen will do the right thing, but a C++ compiler won't know that it should ignore the inner */. An alternative is to use a ///-delimited Doxygen block:

/// documentation
/// \code
/// /*
///     comment 
/// */
/// \endcode

This version won't confuse the C++ compiler, but now Doxygen adds an extra star. How can I make both Doxygen and C++ happy?

doxygen html output

It was suggested in comments that I could at least align the extra asterisk with the ones that are supposed to be there, making the output look better. In some cases that might be acceptable, but I think that would be a problem for me, so let me explain why. The documentation is discussing a renderer shading language that understands #include and single-line comments but not block comments, and wants to say:

Block comment lines are not supported, but may not matter if the included file does not close the block:

/*
  #include "MyFile.h" --> file will be included anyway.
*/

If that gets changed to

/*
 *  #include "MyFile.h" --> file will be included anyway.
 */

then it may look fine, but I don't know if it will be semantically correct any more, because I don't know what that extra asterisk would do.

doxygen c++
2 Answers

As it is not possible to have a code block in a comment and I suggested to maybe use the \snippet command I give an example of it usage here:

/// documentation
/// \snippet this S1
void fie();

// [S1]
 /*
  comment
  */
// [S1]

resulting in:

enter image description here

Note: you can also use e.g.:

/// documentation
/// \snippet this S1
// [S1]
 /*
  comment
  */
// [S1]
void fie();
user_16578860

Personally, I do the opposite.

My docs use /** ... */ and comments within code blocks use //:

/** \brief My doc
 *
 * \code
 *     // this is a comment
 *     here is some code...
 * \endcode
 */

I'm not aware of a way to add C-like comments here. Note that most C compilers now support the C++ comment syntax too.

user_2123780
Related