如何在 doxygen 块内的代码块内显示注释块？

Question

假设我想在一个代码块中显示一个 /* - */ 分隔的注释块 C++ 代码中的 Doxygen 文档块。如果 Doxygen 块，本身就是 /* - */ 分隔，像这样，

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

这显然会成为一个问题：Doxygen 会做正确的事情，但是 C++ 编译器不知道它应该忽略内部 */。另一种方法是使用 ///-分隔的 Doxygen 块：

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

这个版本不会混淆C++编译器，但是现在Doxygen多了一颗星。如何让 Doxygen 和 C++ 都满意？

有人在评论中建议我至少可以将额外的星号与应该存在的星号对齐，使输出看起来更好。在某些情况下，这可能是可以接受的，但我认为这对我来说是个问题，所以让我解释一下原因。文档正在讨论一种理解#include和单行注释但不理解块注释的渲染器着色语言，想说：

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.
*/

如果更改为

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

那么它可能看起来 不错，但我不知道它在语义上是否会更正确，因为我不知道那个额外的星号会做什么。

Answer 1

就个人而言，我相反。

我的文档使用 /** ... */，代码块中的注释使用 //:

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

我不知道在此处添加 C-like 评论的方法。请注意，大多数 C 编译器现在也支持 C++ 注释语法。

Answer 2

由于评论中不可能有代码块，我建议使用 \snippet 命令，我在这里给出了一个用法示例：

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

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

导致：

注意：您也可以使用例如：

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

如何在 doxygen 块内的代码块内显示注释块？

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

c++

doxygen