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。

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

/// 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 输出中没有缩进到同一级别，并且它不在<simplesect kind="remark">XML 输出中的标记下。

我尝试在第二段的开头添加一个@par命令，但这也没有达到我想要的效果。新段落仍然不是“备注”部分的子项。在 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 输出中的<para>标记下的<simplesect kind="remark">标记中，并且在 HTML 输出中视觉关系是正确的。但这很丑陋，对我来说似乎是个错误。

有没有我想念的标准方法来做到这一点？当然，我不是第一个想要在我的文档的“备注”部分中包含多个段落的人……而且这不仅限于@remarks; 例如，同样的事情也会发生@internal。

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

4

4 回答 4

9

您的最终示例代码，即

/// @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(and \remarks, 和 , 一样\remark) 结束在段落的末尾，但是相邻\remark的 s 会被拼接在一起形成一个\remark块。

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

于 2012-09-21T10:20:15.953 回答
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.

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

于 2012-10-11T13:58:04.460 回答
3

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

于 2017-05-03T08:00:12.250 回答
0

解决方案可以概括（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空行中必须填写否。不幸的是，我还没有找到在代码部分之后附加另一个缩进文本段落的方法。

于 2015-10-21T07:28:38.600 回答