Doxygen常用命令

术语和约定

  所有命令都以反斜杠\或@符号开始，使用\还是@取决于你喜欢更哪一种风格。

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

• 如果使用<>尖括号（尖括号不必键入），则表示参数为单个单词；
• 如果使用()括号（圆括号不必键入），则表示参数扩展到找到命令所在行的末尾。
• 如果使用{}花括号（花括号不必键入），则参数扩展到下一段。段落由空白行或段落指示符分隔。注意{}花括号也用于命令选项，这时的花括号是强制的，只是“普通”字符。开始的花括号必须直接跟在命令后面，所以不能有空格。

  如果使用[]方括号（方括号不必键入），参数是可选的，除非它们被放在引号之间，在这种情况下，[]方括号是命令参数的强制部分。

---

记录类型

\def 命令

\def <宏名> 

表明注释块是#define宏的记录。

/*! \def MAX(x,y) * 这里是 MAX(x,y) 宏的记录，这个注释块可以放在文档的其他位置 */ /*! 这里是 MAX(x,y) 宏的记录，这个注释块必须放在宏的前面 */ #define MAX(x,y) ((x)>(y)?(x):(y)) /*!< 这里是 MAX(x,y) 宏的记录，这个注释块必须放在宏的后面 */ 

---

\enum 命令

\enum <枚举名> 

表明注释块是名称为
<枚举名>的枚举记录。如果注释块直接位于enum声明的前面，则\enum注释可以省略。

/*! \enum colour * 这里是枚举 colour 的记录，因为注释块在声明的前面，所以上面的命令是可以省略的 */ enum colour { 
      RED, BULE, GREEN }; 

---

\struct 命令

\struct <结构名> 

表明注释块是名称为
<结构名>的结构体的记录。

---

\union <联合名> 

表明注释块是名称为
<联合名>的联合的记录。

---

\fn 命令

\fn (函数声明) 

表明注释块是函数（全局函数或类的成员函数）的记录。只有当注释块没有放在函数声明或定义的前面（或后面）时，才需要这个命令。如果你的注释块在函数声明或定义的前面，这个命令可以被省略（为了避免冗余）。

/*! \fn int func(char *, int) * 这里是函数 func 的记录，因为注释块在声明的前面，所以上面的命令是可以省略的， */ int func(char *, int); 

---

\var 命令

\var (变量声明) 

表明注释块是变量或枚举值（全局）的记录

---

\typedef 命令

\typedef (类型定义声明) 

表明注释块是 typedef 的记录。

/*! \typedef typedef int uint32_t * 这里是 typedef 的记录 */ typedef int uint32_t; 

---

文件描述

\file 命令

\file [<文件名>] 

表明注释块是名称为
<文件名>的源文件或头文件的记录。如果文件名不是唯一的，文件名可以包含（一部分）路径。如果文件名被省略，则包含\file命令的记录块将属于它所在的文件。

重要：
全局函数、变量、类型定义和枚举的记录只有在它们所在的文件有文件记录或者EXTRACT_ALL被设置为YES时才会包含在输出中。

/*! \file source.c * 这里是 source.c 文件的记录， * 如果没有此文件记录，下面的枚举记录也不会包含在输出中 * 除非 EXTRACT_ALL 配置被设置为 YES */ /*! 这里是枚举记录，如果该文件没有文件记录，则此记录不会被输出， * 除非 EXTRACT_ALL 配置被设置为 YES */ enum colour { 
            RED, BULE, GREEN }; 

---

\author 命令

\author { 
             作者列表 } 

开始一个可以输入一个或多个作者姓名的段落。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\author命令将被合并成一个段落。当遇到空行或其他分段命令时，\author命令结束。

/ * @file * @author 作者，对作者的描述 */ 

---

\date 命令

\date { 
              日期描述 } 

开始一个可以输入一个或多个日期的段。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\date命令将被合并成一个段落，每个日期描述将在新一行开始。或者，一个\date命令可以提到几个日期。当遇到空行或其他分段命令时，\date命令结束。

/ @file * \date xxxx年xx月xx日 */ 

---

\version 命令

\version { 
               版本号 } 

开始一个可以输入一个或多个版本字符串的段落。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\version命令将被合并成一个段落，每个版本描述将从一个新行开始。或者，一个\version命令可能会提到几个版本字符串。当遇到空白行或其他分段命令时，\version命令结束。

---

\copyright 命令

\copyright { 
                版权描述 } 

开始一个描述实体版权的段。这一段将缩进。这段文字没有特殊的内部结构。

/ @file * \copyright 版权描述 */ 

---

\attention 命令

\attention { 
                 注意文本 } 

开始一个需要注意的信息段落。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\attention命令将被合并成一个段落。当遇到空白行或其他分段命令时，\attention命令结束。

/ * @file * 这是文件记录 * @attention 在这里编辑注意信息。 * 这里可以继续编辑，要结束该命令，只需将下一行保留为空行即可 * * @attention 相邻的 attention 命令会被合并为一个段落。 */ 

---

\note 命令

\note { 
                  注解内容 } 

---

---

\warning 命令

\warning { 
                    警告信息 } 

开始一个段落，可以输入一个或多个警告消息。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\warning命令将被合并成一个段落，每个警告描述将在新一行开始。或者，一个\warning命令可能会提到多个警告。当遇到空白行或其他分段命令时，\warning命令结束。

---

\remark 命令

\remark { 
                     备注文本 } 

开始一个可以输入一个或多个备注的段落。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\remark命令将被合并成一个段落，每个备注将在新的一行开始。或者，一个\remark命令可以提到几个备注。当遇到空白行或其他分段命令时，\remark命令结束。

/ @file * \remark 备注文本 */ 

---

\deprecated 命令

\deprecated { 
                      弃用描述 } 

开始一个段，指示此记录块属于已弃用的实体。可用于描述替代品、预期寿命等。

这会生成一个弃用表。

/ @file * \deprecated 弃用描述 */ 

---

函数描述

\brief 命令

\brief { 
                       简要描述 } 

开始一段简要描述。对于函数和文件，简要描述将在列表中显示。

/ * @brief 简要描述 * * 详细描述 */ void fun(void) 

---

\details 命令

\details { 
                        详细描述 } 

就像\brief开始一个简要的描述，\details开始详细的描述。你也可以开始于一个新的段落（空行），这样就不需要\details命令了。

/ @file * \brief 简要描述 * \details 详细描述 */ / @file * \brief 简要描述 * * 详细描述 */ 

---

\param 命令

\param '['方向']' <参数名> { 
                         参数描述 } 

开始一个名称为
<参数名>的函数参数的参数描述 。检查参数是否存在，如果这个（或任何其他）参数的记录缺失或没有出现在函数声明或定义中，则给出一个警告。

\param命令有一个可选属性dir，用来指定参数的方向。可能的值是"[in]"， "[in,out]"，和"[out]"，注意这个描述中的[方括号]，这是必须键入的。

参数描述是一个没有特殊内部结构的段落。所有的视觉增强命令可以在段落内使用。多个相邻的\param命令将被合并成一个段落，每个参数描述将从新的一行开始。当遇到空行或其他分段命令时，\param命令结束。

注意，您也可以使用一个逗号分隔列表来记录多个参数。

/ * @brief 设置坐标 * @param x,y,z 三维空间中的位置坐标 * @param t 时间 */ void setPosition(double x,double y,double z,double t); 

---

\ref 命令

\ref <名称> ["(文本)"] 

创建对指定段、分段、页或锚点的引用。对于HTML文档，\ref命令将生成到该段的链接。对于一个段或分段，段的标题将被用作链接的文本。对于锚点，将使用引号之间的可选文本，如果没有指定文本，则使用
<名称>。

---

\retval 命令

\retval <返回值> { 
                           描述 } 

开始一段名称为
<返回值>函数返回值的描述。构成描述的段落的文本没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\retval命令将被合并成一个段落，每个返回值描述将从新的一行开始。当遇到空行或其他一些分段命令时，\retval描述结束。

---

记录列表

\bug 命令

\bug { 
                            BUG描述 } 

开始报告一个或多个bug的段落。这段将缩进。这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。多个相邻的\bug命令将被合并成一个段落。每个bug描述将在新一行开始。或者，一个\bug命令可能会提到几个bug。当遇到空白行或其他分段命令时，\bug命令结束。

这会生成一个bug表。

---

\test 命令

\test { 
                             描述测试用例的段落 } 

开始一个可以描述测试用例的段落。该描述还将把测试用例添加到一个单独的测试列表中。

---

\todo 命令

\todo { 
                              描述待办事项的段落 } 

开始一个描述待办事项的段落。该描述还将向单独的待办事项列表添加一个项目。

---

组

\defgroup 命令

\defgroup <组名> (组标题) 

表明注释块是一组类、文件或名称空间的记录。这可以用于对类、文件或名称空间进行分类，并记录这些类别。您还可以将组用作其他组的成员，从而构建组的层次结构。


<组名>参数应该是一个单字标识符。

/*! \defgroup mygrp This is my group. * 这里为 mygrp 组添加记录 * @{ */ /*! A function */ void func1() { 
                              } /*! @} */ 

---

\addtogroup 命令

\addtogroup <组名> [(标题)] 

定义一个类似\defgroup的组，但多次使用相同
不会导致警告，而是合并记录到已有的组。

标题是可选的，所以这个命令也可以像这样使用@{
和@}向一个现有的组添加一些实体：

/*! \addtogroup mygrp * 这里为 mygrp 组添加记录 * @{ */ /*! A function */ void func1() { 
                               } /*! @} */ 

---

\ingroup 命令

\ingroup (<组名> [<组名> <组名>]) 

如果\ingroup命令放在文件注释块中，那么它将被添加到以
<组名>标识的一个或多个组中

---

页面

\mainpage 命令

\mainpage [(标题)] 

如果\mainpage命令放置在注释块中，该注释块用于定制索引页(HTML)或第一章(LATEX)。title参数是可选的，它会替换doxygen的默认标题。如果你不想要任何标题，你可以指定notitle作为\mainpage的参数。

/*! \mainpage My Personal Index Page * \section intro_sec Introduction * This is the introduction. * \section install_sec Installation * \subsection step1 Step 1: Opening the box * etc... */ 

---

\page 命令

\page <页面名> (标题) 

表明注释块是与特定文件或成员不直接相关的一段文档。HTML生成器创建一个包含文档的页面。LATEX生成器在“页面文档”一章中启动了一个新的部分。

注意：

<页面名>参数由字母和数字组成。如果你希望在
<页面名>参数中使用大写字母（例如MYPAGE1），或者混合大小写字母（例如MYPAGE1），你应该将CASE_SENSE_NAMES设置为YES。但是，只有当您的文件系统区分大小写时，这才是可取的。否则（为了更好的可移植性），您应该在所有对页面的引用中使用的所有小写字母（例如mypage1）。

---

\subpage 命令

\subpage <子页面名> ["(文本)"] 

该命令可用于创建页面的层次结构。使用\defgroup和\ingroup命令也可以实现相同的结构，但对于页面，\subpage命令通常更方便。主页面（参见\mainpage）通常是层次结构的根。

这个命令的行为类似于\ref，它创建了一个对标签为
<子页面名>的页面的引用，并使用第二个参数指定可选的链接文本。

它与\ref命令的不同之处在于，它只适用于页面，并在页面之间创建父子关系，其中子页面（或子页面）由标签
<子页面名>标识。

如果想添加结构而不创建多个页面，请参阅\section和\subsection命令。

注意：
每个页面只能是另一个页面的子页面，不允许有循环关系，即页面层次结构必须是树状结构。

/*! \mainpage 一个简单的手册 * 一些一般性的信息。 * 本手册分为以下几部分: * - \subpage intro * - \subpage advanced "高级用法" */ //----------------------------------------------------------- /*! \page intro 简介 * 本页面向用户介绍该主题。 * 现在你可以进入 \ref advanced "高级用法" 了。 */ //----------------------------------------------------------- /*! \page advanced 高级用法 * 此页面供高级用户使用。 * 确保你已经阅读了 \ref intro "简介". */ 

---

段落

\section 命令

\section <段名> (段标题) 

创建一个名为
<段名>的段。段的标题由\section命令的第二个参数指定。

警告：
这个命令只在相关页面记录中工作，而不是在其他记录块中！

/*! \page software_page 软件主页索引 * \section intro_sec 简介 * 这里是简介。 * \section install_sec 安装 * \subsection step1 步骤1：双击exe文件 * \subsection step2 步骤2：点击立即安装 * 等等。 */ 

---

\subsection 命令

\subsection <子段名> (子段标题) 

创建一个名为
<子段名>的子段。子段的标题由\subsection命令的第二个参数指定。

警告：
这个命令只在相关页面记录块的一部分内工作，而不在其他记录块中工作！

/*! \page software_page 软件主页索引 * \section intro_sec 简介 * 这里是简介。 * \section install_sec 安装 * \subsection step1 步骤1：双击exe文件 * \subsection step2 步骤2：点击立即安装 * 等等。 */ 

---

\cond 命令

\cond [(段落标签)] 

开始一个以相应的\endcond命令结尾的条件段。这对命令的主要目的是（有条件地）将文件的一部分排除在处理之外（在旧版本的doxygen中，这只能通过C预处理器命令实现）。

在\cond和\endcond之间的段可以通过将其段标签添加到ENABLED_SECTIONS配置选项来包含。如果省略了段标签，该段将被无条件地排除在处理之外。

段标签可以是段标签、圆括号、&&（与）、||（或）和 !（非）构成的逻辑表达式，例如：\cond (!LABEL1 && LABEL2)。

条件段可以嵌套。

---

格式

\par 命令

\par [(段落标题)] { 
                                        段落内容 } 

如果给定了一个段落标题，这个命令以用户定义的标题开始一个段落。标题一直延伸到行尾。命令后面的段落将缩进。

如果没有给出段落标题，这个命令将开始一个新的段落。这也将在其他段落命令（如\param或\warning）中工作，而不会结束这些命令。

这段文字没有特殊的内部结构。所有的视觉增强命令可以在段落内使用。当遇到空行或其他分段命令时，\par命令结束。

/ @file * \par 用户定义段落： * 段落内容 * \par * 同一标题下的新段落。 * \note * 这条注解由两个段落组成。 * 这是第一个段落。 * \par * 这是第二个段落。 * 更多的一般文本。 */ 

---

\parblock 命令

\parblock 

对于期望以单个段落作为参数的命令（例如\par、\param和\warning）， \parblock命令允许开始一个覆盖多个段落的描述，然后以\endparblock结束。

/ * @param p * \parblock * 参数描述的第一段 * * 参数描述的第二段 * \endparblock * 注释块的其余部分继续 */ void fun(int p); 

---

\verbatim 命令

\verbatim 

开始一个将逐字包含在记录中的文本块。块应该以\ endveratim命令结束。在一个逐字块中禁用所有命令。

---

\a 命令

\a <单词> 

以斜体显示参数
<单词>。使用此命令来强调单词。

---

\b 命令

\b <单词> 

使用粗体显示参数
<单词>。相当于< b > < / b >。把多个单词用粗体表示请使用 < b > 多个单词 < / b >。

---

\c 命令

\c <单词> 

使用打字机字体显示参数
<单词>。相当于< tt > < / tt >。

---

\n 命令

\n 

换行。

---

转义

\\ 

该命令将反斜杠字符\写入输出。在某些情况下，反斜杠必须转义，因为doxygen使用它来检测命令。

---

\@ 

这个命令在输出中写入一个@符号。在某些情况下，必须转义@符号，因为doxygen使用它来检测Javadoc命令。

---

\& 

这个命令将&字符写入输出。这个字符必须转义，因为它在HTML中有特殊的含义。

---

\$ 

这个命令将$字符写入输出。在某些情况下，必须转义此字符，因为它用于展开环境变量。

---

\# 

这个命令将#字符写入输出。在某些情况下，必须转义此字符，因为它用于引用记录的实体。

---

\< 

这个命令将<字符写入输出。这个字符必须转义，因为它在HTML中有特殊的含义。

---

\> 

该命令将>字符写入输出。这个字符必须转义，因为它在HTML中有特殊的含义。

---

\% 

这个命令将%字符写入输出。在某些情况下，这个字符必须转义，因为它用于防止自动链接到一个也是文档化类或结构的单词。

---

\" 

这个命令将"字符”写入输出。在某些情况下，必须转义此字符，因为它成对使用以指示未格式化的文本片段。

---

\. 

该命令在输出中写入一个点.。这有助于防止在启用JAVADOC_AUTOBRIEF情况下结束简要描述，或防止在一行开头的数字后面有一个点时开始一个带编号的列表。

---

\= 

这个命令将等号=写入输出。这个字符序列在某些情况下必须转义，因为它被用于Markdown头信息处理。

---

\:: 

这个命令在输出中写入一个双冒号::。在某些情况下，必须转义此字符序列，因为它用于引用记录的实体。

---

\| 

这个命令将一个管道符号|写入输出。在某些情况下，这个字符必须转义，因为它用于Markdown表。

---

\-- 

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

---

\--- 

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

---