我应该如何使用带有选项作为第一个参数的 Doxygen 命令？

Question

我在理解某些将选项作为第一个参数的 Doxygen 命令时遇到了一些麻烦（使用 HTML 输出）。 这里是关于\include 命令，但我相信答案（如果有的话）将适用于其他命令。

manual 说：

如果需要，您可以添加选项 {lineno} 以启用包含代码的行号。

您可以添加选项 {doc} 将文件视为文档而不是代码。

我无法让它工作。 这个：

\include doc path/to/my/file

工作正常。但是文件内容被认为是代码（这是完全正常的），它实际上包含一些我想格式化为文档的生成内容。

我试过这些（是的，请不要笑）：

\include doc path/to/my/file
\include [doc] path/to/my/file
\include {doc} path/to/my/file
\include {[doc]} path/to/my/file
\include [{doc}] path/to/my/file

但这些都不起作用。 lineno 选项的行为相同。

为了完整起见，我不得不提一下，手册提供了一些关于符号 here 的信息：

有些命令有一个或多个参数。每个参数都有一定的范围：

如果使用大括号，则参数是一个单词。

如果使用（圆）大括号，则参数将延伸到找到命令的行的末尾。

如果使用 {curly} 大括号，则参数将延伸到下一段。段落由空行或节指示符分隔。

但我不明白这与\include 命令手册的上述引用有何关系。

有人知道吗？

Doxygen 版本：1.8.11（Ubuntu 16.04 的最新版本）。

Answer 1

首先必须区分不同版本的 doxygen。在 1.8.11 版本中没有选项，例如\include 命令，它们是在 1.8.15 版本中引入的。

例如的语法\include 命令在 1.8.15 中：

\include[{lineno,doc}]

在较新的版本中，这写为：

\include['{'option'}']

重写已完成，因为它并不完全清楚。此处（新版本，但此语法也适用于 1.8.15）方括号（[ 和 ]）表示可选性，'{' 和 '}' 表示大括号是强制性的。在这种情况下，选项可以是lineno 或doc。此外，\include 和大括号之间没有空格，这不应该存在，大括号是命令的一部分。如果出现空格，它将被视为命令的结尾，{ 将是参数的开始。

如果\include 带有文件名xx.h，我们可以：

\include xx.h

\include{lineno} xx.h

\include{dox} xx.h

这是关于选项，另一个引用是关于命令的参数。