如何在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.
 */

那么它可能看起来不错，但我不确定它是否仍然具有语义正确性，因为我不知道那个额外的星号会做什么。

- JWWalker

---

当前版本（1.9.4（5d15657a55555e6181a7830a5c723af75e7577e2））的结果将保持不变。为了回答这个问题，最好在单词“comment”之前在///版本中自己添加*。 - albert

当您添加星号使其看起来像 /// * comment 时，结果将对齐整齐。 - albert

我进行了一些调查，虽然名称可能有点误导，但也许设置MULTILINE_CPP_IS_BRIEF=YES可以帮助您（这对所提出的小案例有效）。 - albert

另一种情况呢？在doxygen块注释中添加行注释？ - Aconcagua

@albert 这是针对Ogre-Next的。我正在尝试纠正其他人编写的文档中的doxygen错误。 - JWWalker

Answer 1

由于在评论中无法使用代码块，我建议可能使用\snippet命令。下面是它的用法示例：

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

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

导致如下结果：

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

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

- albert

Answer 2

就个人而言，我做的是相反的。

我的文档使用/** ... */，代码块内的注释使用//：

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

我不知道在这里添加类似C的注释的方法。请注意，大多数C编译器现在也支持C++注释语法。

- Alexis Wilke