如何在 Doxygen 中的“备注”部分包含多个段落？

Question

如何在 Doxygen 中的“备注”部分包含多个段落？

9

我终于放弃了微软的XML文档格式所施加的尖括号税（而且毫无意义，因为MSVC环境对C++项目仍然不会有任何花哨的处理），并将我的当前项目切换到使用Doxygen和Javadoc风格的语法。

这太棒了。内联文档更易读、易打，生成的输出更有用、更灵活。特别是，我已经打开了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。 问题出现在当我尝试像隐含的“details”部分一样，在我的“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!
///
///     If thread safety is required, the user must handle locking and unlocking
///     the region manually.
void ScrollRegion(int dx, int dy);

生成的输出未将@remarks部分中的第二段解释为备注的一部分。我可以看出，因为它在HTML输出中没有与同一级别缩进，并且不在XML输出中的标签下方。

我尝试在第二段开头添加a @par命令，但是那也没有达到我想要的效果。新段落仍然不是“remarks”部分的子元素。在XML输出中，它被放置在一个新的标签内，该标签是原始标签的同级。

在研究此问题时，我看到有人重复使用了@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"部分中有多个段落的人...这不仅限于@remarks;例如，使用@internal时也会发生同样的事情。

我安装了最新版本的Doxygen（1.8.2），但我非常怀疑这与版本有关。

- Cody Gray

4个回答

4

似乎这里没有提到，但一个解决方案是在每一行末尾加上\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.

这样可以让它呈现出您想要的样子。

- Taeolas

同样，您可以使用<br>标签在段落间进行分隔。 - Patrick Schlüter

这是我解决Doxygen错误的方法，该错误与在TODO中使用@parblock作为将项目列表放入TODO的方式有关。 (@endparblock会破坏隐式的“结束TODO”，从而产生损坏的“Todo List”页面输出。) - ssokolow

3

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

- msc

0

解决方案可以泛化（doxygen 1.8.9.1）。我使用了：

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

程序相关，返回仅翻译文本：
这三个段落是缩进的，标题标题以粗体字打印在它们上面。当然，\par标题可以替换为\备注。魔法短语是段落末尾的\n，可以选择插入空行。空行中不需要\n。不幸的是，我还没有找到一种方法来附加另一个缩进的文本段落跟在代码部分后面。

- hermannk

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Chris · Accepted Answer

您的最终示例代码如下：

/// @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手册（强调我）：

\remark { remark text }

开始一个段落，其中可以输入一个或多个备注。该段落将缩进。段落文本没有特殊的内部结构。所有视觉增强命令都可以在段落内使用。相邻的多个 \remark 命令将连接成一个单独的段落。每个备注将从新的一行开始。或者，一个 \remark 命令可以提到几个备注。 当遇到空白行或其他章节命令时，\remark 命令结束。

因此，\remark （和\remarks ，它与 \remark 相同）在段落末尾结束，但是相邻的 \remark 会被拼接在一起形成一个 \remark 块。

您说这种行为不限于\remarks 和 \remark 是正确的。相同的规则适用于任何需要段落文本作为参数的命令，例如 \bug，\todo，\warning等。