在 doxygen 中使用模块组中的部分

Question

我寻求构建 doxygen 模块组内容的首选方法。例如，我想在不同部分的以下模块组中构造 @details 文本。特别是每个部分都应该出现在生成的 PDF 的书签中（作为模块组的子元素）：

@defgroup lorem
@{
  @brief

  Lorem ipsum

  @details

  Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum
  ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu
  libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu 
  neque.

  Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
  egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum
  urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat.

  Integer sapien est, iaculis in, pretium quis, viverra ac, nunc.
  Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla,
  malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla.
  Donec varius orci eget risus. Duis nibh mi, congue eu, accumsan eleifend,
  sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum.
@}

一种方法可能是使用@section @subsection 等，但 doxygen 手册说：

警告： 此命令仅适用于相关页面文档 而不是在其他文档块中！

是否可以使用@section 或有其他（更好的）方法来做到这一点？

---

编辑： 使用@section 的行为看起来确实很奇怪，例如我尝试过这样的事情：

@defgroup lorem
@{

@brief

Lorem ipsum

@section sec0 Lorem ipsum

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, vestibulum
ut, placerat ac, adipiscing vitae, felis. Curabitur dictum gravida mauris. Nam arcu
libero, nonummy eget, consectetuer id, vulputate a, magna. Donec vehicula augue eu 
neque.

@section sec1 Pellentesque

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis
egestas. Mauris ut leo. Cras viverra metus rhoncus sem. Nulla et lectus vestibulum
urna fringilla ultrices. Phasellus eu tellus sit amet tortor gravida placerat.


@section sec2 Integer sapien est

Integer sapien est, iaculis in, pretium quis, viverra ac, nunc.
Praesent eget sem vel leo ultrices bibendum. Aenean faucibus. Morbi dolor nulla,
malesuada eu, pulvinar at, mollis ac, nulla. Curabitur auctor semper nulla.
Donec varius orci eget risus.
Duis nibh mi, congue eu, accumsan eleifend,
sagittis quis, diam. Duis eget orci sit amet orci dignissim rutrum.

@}

结果看起来很好，在这种情况下，PDF 中的结构如下：

• 4.1 定理
• 4.1.1 Lorem ipsum
• 4.1.2 佩伦特式
• 4.1.3 整数 sapien est

现在，如果添加@file 和@details 部分不包含任何文本出现在输出中，我无法摆脱。看起来像这样（我还测试了添加另一个包含 @file 的组 - 结果相同）：

• 4.1 定理
• 4.1.1 详细说明
• 4.1.2 Lorem ipsum
• 4.1.3 佩伦特式
• 4.1.4 整数 sapien est

然后我尝试移动这些部分并将它们作为“详细描述”的子部分 - 这在逻辑上是可以的。但是当我将它们更改为 @subsection 时，它们会完全消失。在这种情况下，Doxygen 警告说它在节上下文之外找到了一个小节，因此显然它没有意识到它生成了这个神秘的空 @details 节。

下一个想法是使用 Markdown 支持来做到这一点。在这种情况下，部分不会放入 PDF 书签中，因此看起来还不错 - 但在乳胶代码中，它们仍与 @details 部分处于同一级别。 Markdown 中的小节也消失了。我不知道发生了什么，但我不能成为第一个尝试在模块组中构建事物的人。

Answer 1

我自己尝试了您的示例，如果您像这样将@file 放在您的@{ ... @} 之间，

/**
@defgroup lorem
@{
...
@file
@}
*/

然后创建标准的 Doxygen 布局。

如果您将@file 移到外面，那么您喜欢这样，那么它应该可以工作。

/**
@defgroup lorem
@{
...
@}
@file
*/

但是，如果您真的需要 @defgroup lorem @{ ... @} 中的 @file，有两种方法可以实现它。

第一：

/**
@defgroup file
@{
@file
@defgroup lorem
@{
...
@}
@}
*/

第二：

更改标准 doxygen 布局。

要做到这一点，请按照手册说明 here，从：通过创建自定义 DoxygenLayout.xml 更改页面布局开始。

现在，编辑DoxygenLayout.xml 并搜索<group> 标签。

会找到<detaileddescription title=""/> 标签，将其更改为<detaileddescription visible="no" title=""/>，“详细描述”错误应该会消失。

Answer 2

如果您只是想在组描述中构建各个部分，那么我只需使用 HTML 并插入 <h1>Section name here<\h1> 等。

或者 Markdown ## 部分标记可能会起作用。

我不知道这些对 LaTex 和 PDF 的渗透效果如何，因为我从未使用过该输出路径。但是，我相信使用 HTML 将比使用 @section 提供更可靠的结果，正如手册所警告的那样，它根本不是为在这里使用而设计的，而是作为散装散文的 @page / @section / @subsection 层次结构的一部分。这些命令集在 Doxygen 中不能很好地混合。

将@file 定位在奇异的位置（根据aldr 的建议）很容易导致非常奇怪的结果。它只是物理文件的描述块，最好就是这样使用。