如何使用Doxygen在"备注"部分中包含多个段落？

Question

我终于放弃了微软的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),但我非常怀疑这是特定于版本的.

Answer 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手册(强调我的):

\remark { remark text }

开始一个段落,其中可以输入一个或多个备注.该段将缩进.该段的案文没有特殊的内部结构.可以在段落内使用所有视觉增强命令.多个相邻\remark命令将连接到一个段落中.每个评论都将从一个新行开始.或者,一个\remark命令可以提到几个备注.当遇到空行或其他切片命令时,该\remark命令结束.

所以\remark(和\remarks,它是一样的\remark)在段落的末尾结束,但是相邻的\remarks将被拼接在一起形成一个\remark块.

你说这种行为不仅限于\remarks和,你说得对\remark.这同样适用于需要一段文字作为参数,参见,例如任何命令,\bug,\todo,\warning等.