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 lorem
4.1.1 Lorem ipsum
4.1.2 Pellentesque
4.1.3 Integer sapien est

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

4.1 lorem
4.1.1详细说明
4.1.2 Lorem ipsum
4.1.3 Pellentesque
4.1.4 Integer sapien est

然后我尝试移动这些部分并将它们作为“详细描述”的子部分 - 这在逻辑上是合适的。但是当我把它们改成@subsection时，它们就完全消失了。在这种情况下，Doxygen警告它已经在截面上下文中找到了一个子部分，所以显然它没有意识到它生成了这个神秘的空@details部分。

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

Answer 1

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

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

然后创建标准Doxygen布局。

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

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

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

FIRST：

/**
@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的建议）容易导致非常奇怪的结果。它只是物理文件的描述块，最好只用作它。

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

2 个答案: