自定义命令

Doxygen 提供了大量的特殊命令XML 命令HTML 命令,可用于增强或构建注释块内的文档结构。如果您出于某种原因需要定义新命令,可以通过别名定义来实现。

别名的定义应使用 ALIASES 配置标签在配置文件中指定。

简单别名

别名最简单的形式是简单的替换,形式如下:

 name=value

例如,定义以下别名:

 ALIASES += sideeffect="\par Side Effects:^^"

将允许您在文档中使用命令 \sideeffect (或 @sideeffect),这将生成一个带有标题 副作用: 的用户自定义段落。

请注意,您不能在别名的值部分放置 \n 来插入换行符(在生成的输出中)。您可以在别名的值部分放置 ^^ 来插入换行符,就像在原始文件中存在物理换行符一样。

请注意,当您需要在别名的值部分中使用文字 {},(或非默认分隔符)时,您必须使用反斜杠 (\) 对其进行转义,这可能会导致与命令 \{\} 的冲突,对于这些命令,建议使用版本 @{@} 或使用双重转义 (\\{\\})。

另请注意,如果您愿意,可以重新定义现有的特殊命令。

某些命令,例如 \xrefitem,设计为与别名结合使用。

带参数的别名

别名也可以有一个或多个参数。在别名定义中,您需要在花括号之间指定参数的数量。在定义的 value 部分,您可以放置 \x 标记,其中 'x' 表示参数编号,从 1 开始。

这是一个带有单个参数的别名定义的示例:

ALIASES += l{1}="\ref \1"

在注释块中,您可以按如下方式使用它:

/** See \l{SomeClass} for more information. */

这与编写以下代码相同:

/** See \ref SomeClass for more information. */

请注意,您可以通过具有多个参数的版本来重载别名,例如:

ALIASES += l{1}="\ref \1"
ALIASES += l{2}="\ref \1 \"\2\""

请注意,别名定义中的引号必须使用反斜杠进行转义。

通过这些别名定义,我们可以编写:

/** See \l{SomeClass,Some Text} for more information. */

在注释块内,它将扩展为:

/** See \ref SomeClass "Some Text" for more information. */

其中,带有单个参数的命令仍然可以像之前显示的那样工作。

别名也可以用其他别名来表示,例如,可以使用中间的 \xreflist 命令将新命令 \reminder 表示为 \xrefitem,如下所示:

ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"

请注意,如果对于具有多个参数的别名使用逗号作为分隔符,则如果要在命令中放入逗号,则需要使用反斜杠对其进行转义,即:

\l{SomeClass,Some text\, with an escaped comma}

假设上面的示例中 \l 的别名定义。

默认情况下,别名中参数的分隔符是逗号。但是,对于包含大量逗号的参数(例如函数定义的模板),转义每个逗号可能很麻烦。为了解决这个问题,可以直接在参数计数后指定不同的分隔符,例如,要使用分号作为分隔符,可以将命令定义如下:

ALIASES += xreflist{3;}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders;Reminder;Reminders}"

请注意,也允许使用多字符分隔符,即,可以使用双竖线符号作为分隔符来编写相同的示例:

ALIASES += xreflist{3||}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders||Reminder||Reminders}"

允许使用以下字符来创建分隔符:

!#$%&,.?|;:'+=~`/

请注意,对于每个命令和参数数量,可以使用不同的分隔符。但是,不建议为同一命令选择不同的分隔符,因为这可能会导致关于要使用哪个命令定义产生歧义。Doxygen 通过选择与更多参数匹配的命令来解决这种歧义。考虑以下人为的示例:

ALIASES += v{2+}="Choose 2: '\1' and '\2'"
ALIASES += v{3;}="Choose 3: '\1', '\2', and '\3'"

那么:

- \v{One+Two}
- \v{One;Two;Three}
- \v{One+Two;Three;Four}

将产生:

  • 选择 2:'One' 和 'Two'
  • 选择 3:'One'、'Two' 和 'Three'
  • 选择 3:'One+Two'、'Three' 和 'Four'

对于最后一个命令,v 的两个定义都匹配,但选择了具有 3 个参数的定义,因为它匹配的参数更多。

嵌套自定义命令

您可以将命令用作别名的参数,包括使用别名定义的命令。

例如,考虑以下别名定义:

ALIASES += Bold{1}="<b>\1</b>"
ALIASES += Emph{1}="<em>\1</em>"

在注释块中,您现在可以使用:

/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */

这将扩展为:

/** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */


转到下一节或返回索引