Doxygen使用学习（七）------Doxygen的特殊命令字之"用于视觉增强的命令"

今天继续

doxygen

的命令流程学习，用于视觉增强的命令也很常用，特别是你要在程序的注释中使得一些重点语句使得这些语句显示的更加突出，让阅读的人一目了然。

@a

使用一种指定的字体显示

<word>

参数，在运行的文本使用此命令建立与成员参数的引用。例子：

... the \a x and \a y coordinates are used to ...

一下是显示结果：

… the x and y coordinates are used to …

@arg { item-description }

除非该命令后遇到一个空白行或是其他

@arg

命令，此命令都会有一个参数。它可用于生成一个简单的，无嵌套的参数列表。每一个参数都使用一个

@arg

命令开始。例如：

@arg @c AlignLeft left alignment.
@arg @c AlignCenter center alignment.
@arg @c AlignRight right alignment

No other types of alignment are supported.

结果将显示：

AlignLeft left alignment.

AlignCenter center alignment.

AlignRight right alignment

No other types of alignment are supported.

注意：使用HTML命令可创建嵌套列表。

等价于

@li

@b

使用一个黑体显示

<word>

参数，等价于

<b>word</b>

。也可放置多个字，如

<b>multiple words</b>

。

@c

使用一个打印字体显示

<word>

参数，使用该命令引用Word的编码，等价于

<tt>word</tt>

例子：

... This function returns @c void and not @c int ...

以下是结果文本：

… This function returns void and not int …

@code [ ‘{‘’}’]

开始一个代码块，一个代码块的处理不同于普通文本，它默认被解析成C/C++代码，文档化的类和成员的名称将自动被指向文档的连接代替。

@copydoc

从指定的

<link-object>

对象中复制一个文档块，并使用本地命令进行解析。为避免文档块重复的情况，该命令将非常有用，或是用于扩展一个派生成员的文档。

连接对象可指向一个成员(可从属一个类，文件或组)，一个类，一个命名空间，一个组，一个页面或是一个文件(按顺序检查)，注意，如果此对象指向一个成员(从属于函数，变量，类型转换等)，为了使其工作，包含它的复合体(类，文件或组)将被文档化。

为了复制类成员的文档，可在文档中放置一下内容：

/*! @copydoc MyClass::myfunction()
*  More documentation.
*/

如果该成员被重载，可指定相同的参数类型(与成员名之间不留空格)，如下：

//! @copydoc MyClass::myfunction(type1,type2)

如果在文档块中查到请求该成员的文本，则需要有能匹配的名称。

Copydoc命令可用于递归，但递归的每一层级都会暂时中断并记录，如同出现一个错误。

- @copybrief

@copydoc命令的简易工作方式，只复制简明描述，而不处理细节描述

@copydetails

@copydoc命令的简易工作方式，只复制简明描述，而不处理细节描述

@docbookonly

开始一个文本块，这个文本块将仅仅被逐字的包含在生成的

docbook

文档中。这个文本块以

@enddocbookonly

命令结束

@dot [“caption”] [=]

开始一个可包含dot图形描述的文本段，此文本段可用@enddot结束。Doxygen传递文本给dot，并在输出的结果图片(一级图片映射)中包含这些文本。图中的节点是可单击的，且能连接URL。可使用URL中的@ref命令方便的连接doxygen中的条目，例如：

/*! class B */
class B {};
/*! class C */
class C {};
/*! @mainpage
*  Class relations expressed via an inline dot graph:
*  @dot
*  digraph example {
*      node [shape=record, fontname=Helvetica, fontsize=10];
*      b [ label="class B" URL="@ref B"];
*      c [ label="class C" URL="@ref C"];
*      b -> c [ arrowhead="open", style="dashed" ];
*  }
*  @enddot
*  Note that the classes in the above graph are clickable
*  (in the HTML output).
*/

@msc [“caption”] [=]

开始一个可包含消息序列图描述的文本段，查看这个网址的一些例子。此文本段可用命令@endmsc结束。

注意：在msc{…}块中的该文本段只包含消息序列图的一部分。你需要安装mscgen工具，才能使用此命令。例如：

/** Sender class. Can be used to send a command to the server.
*  The receiver will acknowledge the command by calling Ack().
*  @msc
*    Sender,Receiver;
*    Sender->Receiver [label="Command()", URL="@ref Receiver::Command()"];  *    Sender<-Receiver [label="Ack()", URL="@ref Ack()", ID="1"];
*  @endmsc
*/
class Sender
{  public:
/** Acknowledgment from server */
void Ack(bool ok);
};
/** Receiver class. Can be used to receive and execute commands.
*  After execution of a command, the receiver will send an acknowledgment
*  \msc
*    Receiver,Sender;
*    Receiver<-Sender [label="Command()", URL="\ref Command()"];
*    Receiver->Sender [label="Ack()", URL="\ref Sender::Ack()", ID="1"];
*  \endmsc
*/
class Receiver
{
public:
/** Executable a command on the server */
void Command(int commandId);
};

@startuml [{file}] [“caption”] [=]

开始一个可包含一个PlanUML图的有效描述的文本段，查看这个网址的一些例子。此文本段可用命令@enduml结束。

注意：你需要安装Java和PlantUML’s jar文件才能使用此命令。jar文件的名字要使用

PLANTUML_JAR_PATH

指明。

第一个参数是可选的并且作为运行doxygen前的一个预处理步骤，为了和运行PlantUML兼容。你也可以在

@startuml

之后的花括号内增加图像的文件的名字，例如：

@startuml{myimage.png} "Image Caption" width=5cm
Alice -> Bob : Hello
@enduml
```

当指明图像的名字时，doxygen将会产生一个以那个名字命名的图片。如果没有名字，doxygen将会自动选择一个名字。

第二个参数是可选的并且可以用来指明在图片下面的标题。这个参数必须在两个引号之接指明即使它不包含任何空格。引号在标题显示前会被去掉。

第三个参数同样可选可以用来指明图片的高度和宽度。

下面是一个使用了`@startuml`命令的例子：

```C++
/** Sender class. Can be used to send a command to the server.
*  The receiver will acknowledge the command by calling Ack().
*  @startuml
*    Sender->Receiver  : Command()
*    Sender<--Receiver : Ack()
*  @enduml
*/
class Sender
{
public:
/** Acknowledgment from server */
void Ack(bool ok);
};
/** Receiver class. Can be used to receive and execute commands.
*  After execution of a command, the receiver will send an acknowledgment
*  @startuml
*    Receiver<-Sender  : Command()
*    Receiver-->Sender : Ack()
*  @enduml
*/
class Receiver
{
public:
/** Executable a command on the server */
void Command(int commandId);
};

<div class="se-preview-section-delimiter"></div>

@dotfile [“caption”] [=]

在文档中插入一副dot生成的

<file>

图片。

第一个参数指定了图片的名称。Doxygen将会在

DOTFILE_DIRS

标记后指定的路径中查找文件名。如果找到将作为dot工具的输入文件。结果图片将放置到正确的输入目录中。如果dot文件名中包含空格，需要使用引号进行修饰。

第二个参数可选，用于指定图片中显示的标题，即使它没有包含空格也必须放置到引号之前，在标题显示之前引号会被删除。

@mscfile [“caption”] [=]

在文档中插入一副mscgen生成的

<file>

图片。查看这个网址的一些例子。

第一个参数指明了图片的文件名。doxygen将会寻找你指明在

MSCFILE_DIRS

标签后面的路径或文件。如果msc文件被找到，它将被用来作为mscgen工具的输入文件。结果图片将被放到正确的输出目录。如果msc文件名包含空格，你将必须在其周围加上符号(“…”)。

第二个参数是可选的并且可以用来指明在图片下面的标题。这个参数必须在两个引号之接指明即使它不包含任何空格。引号在标题显示前会被去掉。

第三个参数同样可选可以用来指明图片的高度和宽度。

@diafile [“caption”] [=]

在文档中插入一副dia生成的

<file>

图片。

第一个参数指明了图片的文件名。doxygen将会寻找你指明在

DIAFILE_DIRS

标签后面的路径或文件。如果msc文件被找到，它将被用来作为mscgen工具的输入文件。结果图片将被放到正确的输出目录。如果msc文件名包含空格，你将必须在其周围加上符号(“…”)。

第二个参数是可选的并且可以用来指明在图片下面的标题。这个参数必须在两个引号之接指明即使它不包含任何空格。引号在标题显示前会被去掉。

第三个参数同样可选可以用来指明图片的高度和宽度。

@e

使用斜体显示

<word>

，用于突出word。

等价于

@em

，为了突出多个字可用

<em>multiplewords</em>

@em

使用斜体显示

<word>

，用于突出word。

等价于

@e

@endcode

结束一个代码块

也可查看

@code

命令

@enddocbookonly

结束一个

@docbookonly

开始的块

@enddot

结束一个

@dot

开始的块

@endmsc

结束一个

@msc

开始的块

@enduml

结束一个

@enduml

开始的块

@endhtmlonly

结束一个

@htmlonly

开始的块

@endlatexonly

结束一个

@latexonly

开始的块

@endmanonly

结束一个

@manonly

开始的块

@endrtfonly

结束一个

@msc

开始的块

@endverbatim

结束一个

@verbatim

开始的块

@endxmlonly

结束一个

@xmlonly

开始的块

@f$

标记公式文本的开始和结束

@f[

在单独的一行中显示加长公式的起始标记

@f]

在单独的一行中显示加长公式的结束标记

@f{environment}{

在一个指定环境中显示公式的起始标记

@f}

在一个指定环境中显示公式的结束标记

@htmlonly [“[block]”]

开始一个文本块，只能被完整包含在生成的HTML文档中。可用

@endhtmlonly

命令结束。

此命令可为doxygen包含复杂的HTML代码(如applets,java-scripts,html标记)，也可用

@latexonly,@endlatexonly

命令提供一份合适的latex文档。

注意：在一个只包含HTML的块中可以解析环境变量(如$(HOME))

@image [“caption”] [=]

在文档中插入一张图片，图片的格式可指定，如果你希望插入多种格式的图片，那么你必须为每种格式设定一次该命令。

第一个参数指定了输出格式，目前只支持html,latex,docbook 和 rtf.

第二个参数指定图片文件名，doxygen将在

IMAGE_PATH

标记后指定的路径中查找文件名。如果找到将复制到正确的输出目录中。如果图片文件名中包含空格将使用引号修饰。也可以指定一个URL来替代文件名，那么doxygen将不会复制这个图片，而会检查图片是否存在。

第三个参数可选，用于指定图片中显示的标题。即使它没有包含空格也必须放置到引号之中，在标题显示之前引号会被删除。

第四个参数也可选，用于指定图片的高度和宽度。且只对latex输出有效(即format=latex), sizeindication既可用于图片的宽度也可用于图片的高度，该尺寸可在latex中指定一个有效的尺寸(例如10cm或6英寸或是一个符号宽度@textwidth)。

例如：

/*! Here is a snapshot of my new application:
*  \image html application.jpg
*  \image latex application.eps "My application" width=10cm
*/

<div class="se-preview-section-delimiter"></div>

以下是一个可查找的与配置文件关联的例子：

IMAGE_PATH = my_image_dir

警告：HTML中所支持的图片格式受限于浏览器的兼容性。Latex中的图片格式必须是eps(Encapsulated PostScript)。

Doxygen无法检查图片格式是否正确，所以你需要自习确认。

@latexonly

开始一个文本块，只能被完整包含在生成的latex文档中。可用

@endlatexonly

命令结束。

此命令可为doxygen包含复杂的HTML代码(如图片，公式，特殊字符)，也可用

@htmlonly,@endhtmlonly

命令提供一份合适的latex文档。

注意：在一个只包含latex的块中可以解析环境变量(如$(HOME))

@manonly

开始一个文本块，只能被完整包含在生成的MAN文档中。可用

@endmanonly

命令结束。

此命令可为MAN页面中直接包含groff代码，也可用

@htmlonly,@endhtmlonly

命令和

@latexonly,@endlatexonly

命令提供一份合适的HTML和latex文档。

@li { item-description }

除非该命令后遇到一个空白行或是其他

@li

命令，此命令都会有一个参数。它可用于生成一个简单的，无嵌套的参数列表。每一个参数都使用一个

@li

命令开始。

注意：使用HTML命令可创建嵌套列表

等价于

@arg

@n

加入一条新行，等价于

<br>

，可被打印函数使用。

@p

使用打印字体显示

<word>

参数，使用该命令可在运行的文本中引用成员函数。

等价于

@c

@rtfonly

开始一个文本块，只能被完整包含在生成的RTF文档中。可用

@endrtfonly

命令结束。

此命令可为doxygen包含复杂的RFT代码。

注意：在一个只包含RFT的块中可以解析环境变量(如$(HOME))

@verbatim

开始一个能被HTML和latex文档完整包含的文本块，可用

@endverbatim

命令结束，在一个完整块中不允许任何注释。

警告：确认每个

@verbatim

都对应有一个

@endverbatim

，否则解析器将会出现冲突。

@xmlonly

开始一个能被XML完整包含的文本块，可用

@endxmlonly

命令结束。

该命令可用于自定义的XML标记。

@\

写入一个反斜杠到HTML和latex的输出中，因为doxygen可用此斜杠作为命令之间的分隔符，所以大多数情况下它将被忽略。

@@

写入一个at符号到HTML和latex的输出中，因为doxygen可用此符号作为JavaDoc命令之间的分隔符，所以大多数情况下它将被忽略。

@~[LanguageId]

使能/取消一个指定的语言过滤器，用于放置不同语言的文档到一个注释块中，使用

OUTPUT_LANGUAGE

标记过滤掉未指定的语言。使用~[LanguageId]可有效一种输出的指定语言，@~则表示在输出中所有语言均有效。(这也是默认设置的)，例子：

/*! \~english This is English \~dutch Dit is Nederlands \~german Dies ist
Deutsch. \~ output for all languages.
*/

@&

写入一个&符号到输出中，因为此符号在HTML中有特殊函数，所以大多数情况下它将被忽略。

@$

写入一个$符号到输出中，因为此符号可用于扩展环境变量，所以大多数情况下它将被忽略。

@#

写入一个#符号到输出中，因为此符号可用于引用文档化的主体，所以大多数情况下它将被忽略。

@<

写入一个<符号到输出中，因为此符号在HTML中有特殊函数，所以大多数情况下它将被忽略。

@>

写入一个>符号到输出中，因为此符号在HTML中有特殊函数，所以大多数情况下它将被忽略。

@%

写入一个%符号到输出中，因为此符号可防止自动连接到一个文档化或结构中，所以大多数情况下它将被忽略。

@”

写入一个”符号到输出中，因为此符号可用于指示一个无格式的文本段，所以大多数情况下它将被忽略。

以下是一个可查找的与配置文件关联的例子：

`IMAGE_PATH = my_image_dir`

警告：HTML中所支持的图片格式受限于浏览器的兼容性。Latex中的图片格式必须是eps(Encapsulated PostScript)。

Doxygen无法检查图片格式是否正确，所以你需要自习确认。

- @latexonly

开始一个文本块，只能被完整包含在生成的latex文档中。可用`@endlatexonly`命令结束。

此命令可为doxygen包含复杂的HTML代码(如图片，公式，特殊字符)，也可用`@htmlonly,@endhtmlonly`命令提供一份合适的latex文档。

注意：在一个只包含latex的块中可以解析环境变量(如$(HOME))

- @manonly

开始一个文本块，只能被完整包含在生成的MAN文档中。可用`@endmanonly`命令结束。

此命令可为MAN页面中直接包含groff代码，也可用`@htmlonly,@endhtmlonly`命令和`@latexonly,@endlatexonly`命令提供一份合适的HTML和latex文档。

- @li { item-description }

除非该命令后遇到一个空白行或是其他`@li`命令，此命令都会有一个参数。它可用于生成一个简单的，无嵌套的参数列表。每一个参数都使用一个`@li`命令开始。

注意：使用HTML命令可创建嵌套列表

等价于`@arg`

- @n

加入一条新行，等价于`<br>`，可被打印函数使用。

- @p <word>

使用打印字体显示`<word>`参数，使用该命令可在运行的文本中引用成员函数。

等价于`@c`

- @rtfonly

开始一个文本块，只能被完整包含在生成的RTF文档中。可用`@endrtfonly`命令结束。

此命令可为doxygen包含复杂的RFT代码。

注意：在一个只包含RFT的块中可以解析环境变量(如$(HOME))

- @verbatim

开始一个能被HTML和latex文档完整包含的文本块，可用`@endverbatim`命令结束，在一个完整块中不允许任何注释。

警告：确认每个`@verbatim`都对应有一个`@endverbatim`，否则解析器将会出现冲突。

- @xmlonly

开始一个能被XML完整包含的文本块，可用`@endxmlonly`命令结束。

该命令可用于自定义的XML标记。

- @\

写入一个反斜杠到HTML和latex的输出中，因为doxygen可用此斜杠作为命令之间的分隔符，所以大多数情况下它将被忽略。

- @@

写入一个at符号到HTML和latex的输出中，因为doxygen可用此符号作为JavaDoc命令之间的分隔符，所以大多数情况下它将被忽略。

- @~[LanguageId]

使能/取消一个指定的语言过滤器，用于放置不同语言的文档到一个注释块中，使用`OUTPUT_LANGUAGE`标记过滤掉未指定的语言。使用~[LanguageId]可有效一种输出的指定语言，@~则表示在输出中所有语言均有效。(这也是默认设置的)，例子：

```C++
/*! \~english This is English \~dutch Dit is Nederlands \~german Dies ist
Deutsch. \~ output for all languages.
*/

@&

写入一个&符号到输出中，因为此符号在HTML中有特殊函数，所以大多数情况下它将被忽略。

@$

写入一个$符号到输出中，因为此符号可用于扩展环境变量，所以大多数情况下它将被忽略。

@#

写入一个#符号到输出中，因为此符号可用于引用文档化的主体，所以大多数情况下它将被忽略。

@<

写入一个<符号到输出中，因为此符号在HTML中有特殊函数，所以大多数情况下它将被忽略。

@>

写入一个>符号到输出中，因为此符号在HTML中有特殊函数，所以大多数情况下它将被忽略。

@%

写入一个%符号到输出中，因为此符号可防止自动连接到一个文档化或结构中，所以大多数情况下它将被忽略。

@”

写入一个”符号到输出中，因为此符号可用于指示一个无格式的文本段，所以大多数情况下它将被忽略。

@.

这个命令在输出中写一个点号(.)。这个在一下两种情况下比较有用：1.可以当

JAVADOC_AUTOBRIEF

设置为可使用的时候防止结束一个简短的描述。2. 可以防止开始一个数列当有一个点号要跟在一个数字后面时。

@::

这个命令在输出中写一个双冒号(::)。

@|

这个命令在输出中写一个管道号(|)。这个符号在某些情况下要被避开，因为它也被用于Markdown表格。

@–

这个命令写了两个破折号(–)。这允许连续两个破折号写入输出而不是一个n-dash字符(-)。

@—

这个命令写三个破折号(—)输出。这允许写三个连续的破折号输出而不是一个m-dash字符(-)。