如何使用 Doxygen 在“备注”部分包含多个段落？答案

【问题标题】：How do I include multiple paragraphs in the "remarks" section using Doxygen?如何使用 Doxygen 在“备注”部分包含多个段落？
【发布时间】：2012-09-13 11:07:27
【问题描述】：

我终于放弃了微软的 XML 文档格式强加给我的尖括号税（还有什么意义，因为 MSVC 环境仍然对 C++ 项目没有任何花哨的功能) 并将我当前的项目切换为使用带有 Javadoc 样式语法的 Doxygen。

太棒了。内联文档更易于阅读和输入，生成的输出更加有用和通用。特别是，我打开了MULTILINE_CPP_IS_BRIEF 选项，它允许我根据需要编写尽可能长的“简要”描述，然后使用空行将我的“详细信息”文档分成段落。换句话说：

/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
///    Note that this function is reentrant, but not thread-safe!
void ScrollRegion(int dx, int dy);

这正是我想要的输出，同时减少了我必须使用的嘈杂元命令的数量，例如 @brief 和 \details。

当我尝试在“备注”部分添加第二段时出现问题，就像我（隐含地）为“详细信息”部分所做的那样。例如：

/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
///     Note that this function is reentrant, but not thread-safe!
///
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.
void ScrollRegion(int dx, int dy);

生成的输出不会将 @remarks 部分中的第二段解释为备注的一部分。我可以判断，因为它在 HTML 输出中没有缩进到同一级别，而且它不在 XML 输出中的 <simplesect kind="remark"> 标记下。

我尝试在第二段的开头添加a @par command，但这也没有达到我想要的效果。新段落仍然不是“备注”部分的子项。在 XML 输出中，它被放置在一个新的 <simplesect kind="para"> 标记内，该标记是原始 <simplesect kind="remark"> 标记的兄弟。

在研究这个时，我看到其他人复制了 @remarks 命令：

/// Changes the active viewing area of the currently selected region.
///
/// The modification is merely enqueued. This function has no effect until the
/// FlushRegion() function is called.
///
/// Newly-exposed regions will not be repainted automatically. The user must also
/// call the UpdateRegion() function on these regions to cause their contents to
/// be redrawn.
///
/// @param dx The amount, in pixels, to shift the visible region horizontally.
/// @param dy The amount, in pixels, to shift the visible region vertically.
///
/// @remarks
///     Note that this function is reentrant, but not thread-safe!
/// @remarks
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.
void ScrollRegion(int dx, int dy);

确实产生了我想要的输出。这两个段落都嵌套在XML输出中<simplesect kind="remark">标签下的<para>标签中，在HTML输出中视觉关系是正确的。但这很丑陋，对我来说似乎是个错误。

是否有一种标准的方法可以做到这一点，我错过了？ 当然，我不是第一个想要在我的文档的“备注”部分中包含多个段落的人......而且这个不限于@remarks；例如，@internal 也会发生同样的事情。

我安装了最新版本的 Doxygen (1.8.2)，但我非常怀疑这是特定于版本的。

【问题讨论】：

标签： doxygen

【解决方案1】：

您的最后一个示例代码，即

/// @remarks
///     Note that this function is reentrant, but not thread-safe!
/// @remarks
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.

正是\remarks 用于多段注释块的预期用途。来自doxygen manual（强调我的）：

\remark { remark text }

开始一个可以输入一个或多个备注的段落。该段落将缩进。段落的文本没有特殊的内部结构。所有视觉增强命令都可以在段落内使用。 多个相邻的\remark 命令将合并为一个段落。 每条注释都将在新行开始。或者，一个\remark 命令可能会提到几个注释。 \remark 命令在遇到空行或某些其他分段命令时结束。

所以\remark（和\remarks，与\remark相同）结束于段落的末尾，但相邻的\remarks将被拼接在一起形成一个\remark块。

您说得对，这种行为不仅限于\remarks 和\remark。这同样适用于任何将一段文本作为参数的命令，例如，参见\bug、\todo、\warning 等。

【讨论】：

嗯，是的，我读到了，但第一个粗体部分正是让我感到困惑的地方。它表示多个相邻的\remark 命令将合并为一个段落。那不是我想要的。我想要分开段落。但是接下来的句子确实继续说“每个评论都将在新的一行开始”，所以这可能只是一个文档错误。它可能应该说“块”或“部分”，而不是“段落”。很高兴知道这是官方解决方案，尽管我仍然认为它看起来像一个错误。
你说得对，我忽略了这一点。鉴于您在问题中提到的行为，我认为这一定只是一个文档错误。这就是为什么我认为使用\remark 而不是\remarks 更容易混淆。如果您不喜欢文档的外观，我将完全删除 \remarks 或将这两个注释合二为一：即 \remark Note that this function is reentrant, but not thread-safe! If thread safety is required, the user must handle locking and unlocking the region manually.
确实，输入\remark 让我感觉好一些。感谢您的提示！

【解决方案2】：

我在这里没有提到的一个似乎可行的解决方案是用 \n 结束你的行。这会将所有内容组合在一起，同时放入您可能希望看到的空白区域。

如果你想要一个空行，确保上面的行有\n，并且你有一个空行，上面有\n。

在你的例子中，你会想要：

/// @remarks
///     Note that this function is reentrant, but not thread-safe!\n
///     \n
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.

这应该让它看起来像你想要的那样。

【讨论】：

同样你可以用
标签分隔段落。
这就是我解决 Doxygen 错误的方法，该错误与在 @todo 中使用 @parblock 作为将项目符号列表放入 TODO 的一种方式有关。（@endparblock 会破坏隐含的“结束 TODO”，产生损坏的“Todo List”页面输出。）

【解决方案3】：

如果您不喜欢在源代码中为多段备注使用多个@remarks 行，我认为您可以使用@parblock 和@endparblock 为单个@remark 包含多个段落。

【讨论】：

【解决方案4】：

解决方案可以推广（doxygen 1.8.9.1）。我用过：

/// \par Title
/// text of paragraph 1\n
///
/// text of paragraph 2\n
///
/// ~~~
/// Some code / sketch
/// ~~~

kjkAe4Wbasj6 这三个段落是缩进的，标题Title 在它们上方以粗体字母打印。当然\par Title可以换成\remark。神奇的短语是段落末尾的\n，可以选择插入空行。空行中不需要\n。不幸的是，我还没有找到在代码部分后面附加另一个 indented 文本段落的方法。

【讨论】：