Doxygen 提供了大量的 特殊命令、XML 命令 和 HTML 命令,可用于增强或组织注释块内的文档。如果您出于某种原因需要定义新命令,可以通过别名定义来实现。
别名的定义应在配置文件中使用 ALIASES 配置标签指定。
别名最简单的形式是简单的替换,其形式为
name=value
例如,定义以下别名
ALIASES += sideeffect="\par Side Effects:^^"
这将允许您在文档中放入命令 \sideeffect (或 @sideeffect),这会生成一个用户定义的段落,其标题为 副作用:。
请注意,您不能在别名的值部分中放入 \n 来插入换行符(在生成的输出中)。您可以在别名的值部分中放入 ^^ 来插入换行符,就如同原始文件中存在物理换行符一样。
请注意,当您需要在别名的值部分中使用字面量 { 或 } 或 ,(或非默认分隔符)时,您必须通过反斜杠 (\) 进行转义,这可能与命令 \{
和 \}
冲突,对于这些情况,建议使用 @{
和 @}
版本或使用双反斜杠转义 (\\{
和 \\}
)
另请注意,如果您愿意,可以重新定义现有的特殊命令。
某些命令,例如 \xrefitem,设计用于与别名结合使用。
别名也可以带一个或多个参数。在别名定义中,您需要在花括号之间指定参数的数量。在定义的值部分,您可以放置 \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. */
其中带单个参数的命令仍然可以像之前展示的那样工作。
别名也可以用其他别名表示,例如,一个新的命令 \reminder 可以通过一个中间的 \xreflist 命令表示为 \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}
将生成
对于最后一个命令,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. */