Doxygen使用学习（三）------Doxygen的特殊命令字之"结构类的表达"

Doxygen的特殊命令字

Doxygen在进行注释的时候，有很多以@或者\开头后面加上一个特殊命令的字段，然后就可以在生成文档的时候有特殊的作用，我一般喜欢用@，所以后面的命令都使用这个标签，下面我来介绍一下。

结构类的表达

• @addtogroup [(title)]

使用@defgroup同样可以定义一个组，但是相比之下，多次使用相同<name>的@addtogroup命令并不会出现警告，而它是一个将命令中附带的title与文档进行合并的组。
title是可选的，所以该命令可以使用@{和@}添加一定数量的实体到一个已存在的组里。例如：

/*! \addtogroup mygrp
   *  Additional documentation for group 'mygrp'
   *  @{
   */

  /*!
   *  A function
   */
  void func1()
  {
  }

  /*! Another function */
  void func2()
  {
  }

  /*! @} */

• @callgraph

当该命令放置到一个函数或方法的注释块中，且HAVE_DOT设为YES，doxygen将创建一个调用图。

• @callergraph

当该命令放置到一个函数或方法的注释块中，且HAVE_DOT设为YES，doxygen将创建一个调用者图。

• @hidecallgraph

当该命令放置到一个函数或方法的注释块中，且HAVE_DOT设为YES，doxygen将不创建一个调用图。

• @hidecallergraph

当该命令放置到一个函数或方法的注释块中，且HAVE_DOT设为YES，doxygen将不创建一个调用者图。

• @category [] []

只适用于Object-C：为一个名为<name>的类指定一个文档注释块，此命令参数应与@class相同

• @class [] []

为一个名字为<name>类指定一个文档注释块，可选择指定的一个头文件和一个头名称。如果指定了一个头文件，在HTML文档中将包含一个指向次头文件的完全副本的链接。<header-name>参数可用于覆盖<header-file>之外的类文档中所使用链接名称，如果在默认包含路径中无法定位包含文件(如

/* A dummy class */
class Test
{
};
/*! \class Test class.h "inc/class.h" 
 *  \brief This is a test class. 
 * 
 * Some details about the Test class. 
 */

• @def

用于定义一个#define的注释，例如：

/*! \file define.h    
    \brief testing defines

    This is to test the documentation of defines.
*/
/*! \def MAX(x,y) 
    Computes the maximum of \a x and \a y.
*/
/*!    
    Computes the absolute value of its argument \a x.
*/
#define ABS(x) (((x)>0)?(x):-(x))
#define MAX(x,y) ((x)>(y)?(x):(y))
#define MIN(x,y) ((x)>(y)?(y):(x))         
    /*!< Computes the minimum of \a x and \a y. */

• @defgroup (group title)

为类、文件或命名空间的组，指定一个文档注释块，可以用于类、文件、命名空间和文档的其他类别进行归类，也可以将组作为其他组的成员，这样就可以创建一个组的层次。

• @dir []

为一个目录指定一个文档注释块，path fragment参数应包含一个路径名和一个与项目中其他路径不一样的唯一一个全路径(The “path fragment” argument should include the directory name and enough of the path to be unique with respect to the other directories in the project.)

• enum

为一个名字为<name>的枚举类型指定一个文档注释块，如果此枚举是类中的一个成员，且文档块处于类定义之外，类的作用于同样需要指定。如果一个注释块位于枚举声明之前，那么@enum注释可能被省略。
注意：一个无名的枚举类型将不能被文档化，但一个无名的枚举值是可以使用的。
例如：

class Enum_Test
{  
public:    
    enum TEnum { Val1, Val2 };    
    /*! Another enum, with inline docs */    
    enum AnotherEnum     
    {       
        V1, /*!< value 1 */      
        V2  /*!< value 2 */    
    };
};

/*! \class Enum_Test 
 * The class description. 
 */
/*! @enum Enum_Test::TEnum 
 * A description of the enum type. 
 */
/*! @var Enum_Test::TEnum Enum_Test::Val1 
 * The description of the first enum value. 
*/

• @example

为一个源码的例子指定一个文档注释块，<file-name>是源码文件名，在注释块包含的文档之后，将包含此文件的文本。所有的例子将被放入一个列表中，为了已文档化的成员和类，与文档之间的交叉引用，将对源码进行扫描，源文件或目录将在doxygen的配置文件中使用EXAMPLE_PATH标记指定。

如果<file-name>也就是在EXAMPLE_PATH标记指定的例子文件名，并非是唯一的，你需要包含它的绝对路径，以消除它的二义性。

如果例子中需要多个源文件，可以使用@include命令，例如：

/** A Example_Test class. 
 *  More details about this class. 
 */
class Example_Test
{
public:    
/** An example member function.     
 *  More details about this function.    
 */    
 void example();
};
void Example_Test::example() {}
/** @example example_test.cpp 
 * This is an example of how to use the Example_Test class. 
 * More details about this example. 
 */

下面是例子文件example_test.cpp

void main()
{ 
    Example_Test t; 
    t.example();
}

• @endinternal

这个命令结束一个以@internal开头的文档块。只要当INTERNAL_DOCS设置为YES时在@internal和@endinternal之间的文档才可见。

• @extends

当编程语言不支持这个特性时，比如C语言，就用这个命令手动指定一个继承关系，。

在例子目录中manual.c文件将显示如何使用这个命令。

• @file []

为一个名字为<name>的源文件或者头文件，指定一个文档注释块。如果文件名本身并不是唯一的，那么这个文件名可能包含(部分包含)了它的路径，如果该文件名被省略(如@file后留空)，那么包含@file命令的文档块将属于它已定位到的那个文件。

要点：全局函数，变量，类型转换，枚举的文档只能包含在输出中，并且他们也已被文档化。

例子：

/** @file file.h 
 * A brief file description. 
 * A more elaborated file description. 
 */
/** 
 * A global integer value. 
 * More details about this value. 
 */
extern int globalValue;

注意：上面的例子中JAVADOC_AUTOBRIEF已经设置为YES

• @fn (function declaration)

为一个函数(全局函数或者类的成员函数)指定一个文档注释块，此命令只有在一个注释块没有放到函数声明前面或者后面时才需要。

如果注释块放到了函数声明的前面或者后面，此命令可省略(为了避免重复)。

警告：在此命名并非绝对需要时不要使用，否则将导致信息重复的错误。

class Fn_Test
{ 
public: 
    const char *member(char,int) throw(std::out_of_range);
};
const char *Fn_Test::member(char c,int n) throw(std::out_of_range) {}
/*! @class Fn_Test 
 * @brief Fn_Test class. 
 * 
 * Details about Fn_Test. 
 */
/*! @fn const char *Fn_Test::member(char c,int n)  
 *  @brief A member function.
 *  @param c a character.
 *  @param n an integer. 
 *  @exception std::out_of_range parameter is out of range. 
 *  @return a character pointer. 
 */

• @headerfile []

用于类，结构，联合的文档，同时这些文档都位于它们定义的前面。此命令的参数与@cmdclass命令的第二、三个参数相同。header-file名称会引用一个文件，它能被应用程序为获取类，结构，联合的定义而包含。<header-name>参数可用于覆盖<header-file>之外的类文档中所使用链接名称，如果在默认包含路径中无法定位包含文件(如

@headerfile test.h "test.h"
@headerfile test.h ""
@headerfile "" 

使用尖括号时你无需指定目标，如果你希望明确地指出，也可以使用一下方式：

@headerfile test.h <test.h>
@headerfile test.h <>
@headerfile <> 

• @hideinitializer

一个定义的缺省值和一个变量的初始化都将显示在文档中，除非它们的行数超过30。放置该命令在一个定义或者变量的注释块中，初始化将一直被隐藏。

• @idlexcept

表明了该注释块包含的文档是为了一个名字为<name>的IDL异常

• @implements

用于手动指定一个继承关系，当编程语言不支持这个特性时(如C语言)。

• @ingroup ( [ ])

若该命令被放置到一个类，文件，命名空间的注释块中，它将添加一个<groupname>的组或者是组id。

• @interface [] []

为一个名字为<name>的接口指定一个文档注释块，参数与@class命令相同

• @internal

该命令开始一个仅仅为了内部使用的文档段，这个段落在注释块结尾处结束。你也可以通过使用命令@endinternal提前结束该内部文档段。

如果该命令被放置的一个小节中(见@section中的例子)，那么命令后的所有子小节将被看成internal，只有与其在同一层级的新节才能重新可见。

• @mainpage [(title)]

如果该命令被放置到一个注释块，此块将被用于定制HTML的索引页，或latex的首章。这个很常用，就是生成段落的开始页面的内容，我一开始研究了好久才在stackoverflow上面查到应该这样用！！

title参数是可选的，并能替换掉doxygen生成的默认标题。如果你不需要任何标题，可以在命令后指定notitle。
例如：

/*! \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...
 */

• @memberof

该命令使得类中的一个成员函数与@relates有相同的功能。 只有用这个命令函数才能被表述为一个类的真正成员。当编程语言不支持成员函数的概念时它将非常有用(如C语言)。

• @name [(header)]

该命令将成员组中的头定义转变成一个注释块，注释块将位于一个包含成员组的//@{ ... //@} 块。

• @namespace

为一个名字为<name>的命名空间指定一个文档注释块

• @nosubgrouping

可放置在一个类文档中，用于在合并成员组时，避免doxygen放置一个公有，保护或者私有的子分组。

• @overload [(function declaration)]

用于为一个重载成员函数生成后续的标准文本：这是一个未来便利而提供的重载函数，它不同于上述函数，只包含那些它接受的参数。

如果在函数声明或者定义之前，无法定位重载成员函数的文档，能用可选参数来指定正确的函数。在生成的消息之后将会附带文档块内其他的文档。

注意：你要承担起确认文档的重载成员正确与否的责任，在这种情况下为了防止文档重新排列，必须将SORT_MEMBER_DOCS设置为NO。

注意：在一行注释中@overload命令无法工作

例如：

class Overload_Test 
{
public: 
    void drawRect(int,int,int,int); 
    void drawRect(const Rect &r);
};
void Overload_Test::drawRect(int x,int y,int w,int h) {}
void Overload_Test::drawRect(const Rect &r) {}
/*! @class Overload_Test 
 *  @brief A short description. 
 *
 *  More text. 
 */
/*! @fn void Overload_Test::drawRect(int x,int y,int w,int h) 
 * This command draws a rectangle with a left upper corner at ( \a x , \a y ), 
 * width \a w and height \a h.  
 */
/*!
 * @overload void Overload_Test::drawRect(const Rect &r) 
 */

• @package

为一个名字为<name>的Java包指定一个文档注释块。

• @page (title)

指定一个注释块，它包含了一个与特定的类，文件，成员非直接关联的文档块。HTML生成器将创建一个包含此文档的页面，而latex生成器将在’页文档’的章节中开始一个新的小节。

例如：

/*! @page page1 A documentation page  
    @tableofcontents  Leading text.  
    @section sec An example section  This page contains the subsections @ref subsection1 and @ref subsection2.  
    For more info see page @ref page2.  
    @subsection subsection1 The first subsection  Text.  
    @subsection subsection2 The second subsection  
    More text.
 */
/*! @page page2 Another page  
    Even more info.
*/

• @private

指定注释块中的私有文档化成员，它只能被同一类的其他成员访问。

注意：doxygen会自动确认面对对象语言中的成员保护层级，此命令用于不支持保护层级的概念的语言。(如C语言和PHP4)

私有成员小节的开始处，有一种与C++中private:类似的标记法，使用@privatesection

• @privatesection

开始一个私有成员的小节，与C++中private类似的标记法，指定注释块中的私有文档化成员，它只能被同一类的其他成员访问。

• @property (qualified property name)

为一个属性(即可是全局也可是一个类成员)指定一个文档注释块，此命令等价于@var @fn

• @protected

指定注释文档中的保护文档化成员，它只能被同一类的其他成员或派生类访问。

注意：doxygen会自动确认面对对象语言中的成员保护层级，此命令用于不支持保护层级的概念的语言。(如C语言和PHP4)

保护成员开始处，有一种与C++中protected:类似的标记法，使用@privatesection

• @protocol [] []

为Object-C中名字为<name>的协议指定一个文档注释块，它的参数与@class相同。

• @public

指定注释文档中的公有文档化成员，它只能其他类或函数访问。

注意：doxygen会自动确认面对对象语言中的公有层级，此命令用于不支持公有层级的概念的语言。(如C语言和PHP4)

公有成员开始处，有一种与C++中public:类似的标记法，使用@publicsection

• @pure

指定注释文档中纯虚成员，它是抽象的没有被实施的成员。

注意：此命令用于不支纯虚方法的概念的语言。(如C语言和PHP4)

• @relates

用于名字为<name>非成员函数的文档，它可以放置在这个函数到类文档的“关联函数”小节内，该命令对于非友元函数与类之间建立强耦合是非常有用的。它无法用于文件，只能用于函数。

/*!  
 * A String class. 
 */
class String
{ 
    friend int strcmp(const String &,const String &);
};
/*! 
 * Compares two strings. 
 */
int strcmp(const String &s1,const String &s2)
{
}
/*! @relates String 
 * A string debug function. 
 */
void stringDebug() 
{
}

• @related

同@relates

• @relatesalso

用于名字为<name>非成员函数的文档，它可以放置在这个函数到类文档的“关联函数”小节内，也可是远离它正常文档的位置。该命令对于非友元函数与类之间建立强耦合是非常有用的。只能用于函数。

• @showinitializer

只显示定义的默认值和变量的初始化，如果它们的文本行数小于30，在变量或定义的注释块中放置这个命令，初始化过程将无条件被显示出来。

• @static

指定注释文档中静态成员，它定义在类中，但不属于类的实例化，它属于整个类！

注意：此命令用于不支静态方法的概念的语言。(如C语言和PHP4)

• @struct [] []

为一个名字为<name>的结构体指定一个文档注释块，它与参数@class相同

• @typedef (typedef declaration)

为一个类型转换指定一个文档注释块，它与参数@var @fn相同

• @union [] []

为一个名字为<name>的联合体指定一个文档注释块，它与参数@class相同

• @var (variable declaration)

为一个变量或者枚举值指定一个文档注释块，它与参数@typedef @fn相同

• @vhdlflow [(title for the flow chart)]

这是一个硬件描述语言特定的命令，可以放在文档中产生一个逻辑过程的流程图。流程图的标题可以随意指定。

• @weakgroup [(title)]

用法与@addtogroup相似，但当解决组定义冲突时，它将会有一个更低的优先级。