DoxyGen文档之七

类别:软件工程 点击:0 评论:0 推荐:
第四章:Grouping归组

Doxygen有两种机制进行归组。第一种是全局级,为每个group创建一个新的page。这些groups在注释中被称作“modules”。另一种机制使用于一些compound entity中的member list,称为“member group”。

Modules模块

Modules是一种归组things在分离的page上的方式。组的成员可以是file,namespace,classes,functions,variables,enums,typedefs和defines,但也可以是其他groups。

 

要定义一个group,应该在一个特殊注释块放置\defgroup。命令的第一个参数应该是唯一标志该group的标签。要将一个entity归为某个group的一个member,在entity前放置\ingroup命令。第二个参数是group的title。

 

要避免在注释中每个member前放置\ingroup命令,可以将member用@{和@}封装起来。@{@}标记可以放置group的注释中,也可以在一个独立的注释块

使用这些group的标记符号groups也可以嵌套。

 

如果多次使用一个group标签,将会出错。如果不希望doxygen强行执行唯一标签,可以使用\addtogroup而非\defgroup。运作方式和\defgroup很像,但是如果该group已经定义,它默认向已存在的注释中添加一个新的项。Group的title对此命令是可选的,也可以考虑使用它。

 

/** \addtogroup <label> */

/*\@{*/

/*\@}*/

这样可以在其他地方以更加详细的说明添加members到一个group

 

注意compound entities(例如classes,files和namespaces)可以放在多个groups中,但是members(例如variables,functions,typedefs和enmus)只可以归于一个group(这个限制是为了避免链接目标的ambiguous)。

 

Doxygen将members放在有最高优先级的gourp之中:f.i. \ingroup高于任何使用@{@}的自动归组。和同等的优先级group定义冲突将触发一个警告,除非one definition was for a member without any explicit documentation。下面的例子将VarInA放在group A中,并默认将IntegerVariable放入group IntVariables解决和IntegerVariable的冲突,因为IntegerVariable的第二个instance是未作注释的:

 

/**

 * \ingroup A

 */

extern int VarInA;

 

/**

 * \defgroup IntVariables Global integer variables

 */

/*@{*/

 

/** an integer variable */

extern int IntegerVariable;

 

/*@}*/

 

....

 

/**

 * \defgroup Variables Global variables

 */

/*@{*/

 

/** a variable in group A */

int VarInA;

 

int IntegerVariable;

 

/*@}*/

Group定义命令的优先级(从高到低):\ingroup,\defgroup,\addtogroup,\weakgroup。而\weakgroup很像一个有低优先级的\addtogroup。它被设计为实现一个“lazy”的group定义方法:可以在.h文件中使用高优先级来定义结构,在.cpp文件中使用\weakgroup这样不会重复.h文件中的层次结构。(译注:是否就是说,还可以这样的话还可以在.cpp文件中再作一次group动作?例如,在.cpp文件中又定义了几个nonmember functions,这时可以将使用nonmember function和以前尽管在.h已经做了group的member functions放在一起。)

Example:

/** @defgroup group1 The First Group

 *  This is the first group

 *  @{

 */

 

/** @brief class C1 in group 1 */

class C1 {};

 

/** @brief class C2 in group 1 */

class C2 {};

 

/** function in group 1 */

void func() {}

 

/** @} */ // end of group1

 

 

/**

 *  @defgroup group2 The Second Group

 *  This is the second group

 */

 

/** @defgroup group3 The Third Group

 *  This is the third group

 */

 

/** @defgroup group4 The Fourth Group

 *  @ingroup group3

 *  Group 4 is a subgroup of group 3

 */

 

/**

 *  @ingroup group2

 *  @brief class C3 in group 2

 */

class C3 {};

 

/** @ingroup group2

 *  @brief class C4 in group 2

 */

class C4 {};

 

/** @ingroup group3

 *  @brief class C5 in @link group3 the third group@endlink.

 */

class C5 {};

 

/** @ingroup group1 group2 group3 group4

 *  namespace N1 is in four groups

 *  @sa @link group1 The first group@endlink, group2, group3, group4

 *

 *  Also see @ref mypage2

 */

namespace N1 {};

 

/** @file

 *  @ingroup group3

 *  @brief this file in group 3

 */

 

/** @defgroup group5 The Fifth Group

 *  This is the fifth group

 *  @{

 */

 

/** @page mypage1 This is a section in group 5

 *  Text of the first section

 */

 

/** @page mypage2 This is another section in group 5

 *  Text of the second section

 */

 

/** @} */ // end of group5

 

/** @addtogroup group1

 * 

 *  More documentation for the first group.

 *  @{

 */

 

/** another function in group 1 */

void func2() {}

 

/** yet another function in group 1 */

void func3() {}

 

/** @} */ // end of group1

 

Click here for the corresponding HTML documentation that is generated by Doxygen.

Member Groups

如果一个compound(例如一个class或file)有多个members,通常我们希望将其group。Doxygen已经可以自动按照类型和protection级别将这些things归组在一起,但可能你会认为仅仅这样是不够的或者这种缺省的方法是错误的。例如你认为有不同(语法)的类型需要归入同一个group(语意)。

这样定义一个member group:

//@{

  ...

//@}

块或者使用

/*@{*/

  ...

/*@}*/

块如果你更喜欢C style注释。需要注意的是所有的members必须写在其中。

 

在//@{之前还可以加一个注释块,这个注释块应该包含@name(或者\name)来指明group的header。可选的,这个注释块可以包含group的更详细的信息。

 

Member groups不允许使用嵌套。

如果一个类中的某个member group中所有的members有相同的type和protection level(例如都是static public members),那么这整个都会作为该type/protection level group的subgroup显式出来(例如,这个group作为“static public members”section的subsection)。如果两个或更多成员有不同的类型,那么这个group会和自动产生的groups放在同一个level。如果你希望一个类中所有的member-groups都在top level,可以在类的注释块中使用\nosubgrouping命令。

Example:

/** A class. Details */

class Test

{

  public:

    //@{

    /** Same documentation for both members. Details */

    void func1InGroup1();

    void func2InGroup1();

    //@}

 

    /** Function without group. Details. */

    void ungroupedFunction();

    void func1InGroup2();

  protected:

    void func2InGroup2();

};

 

void Test::func1InGroup1() {}

void Test::func2InGroup1() {}

 

/** @name Group2

 *  Description of group 2.

 */

//@{

/** Function 2 in group 2. Details. */

void Test::func2InGroup2() {}

/** Function 1 in group 2. Details. */

void Test::func1InGroup2() {}

//@}

 

/*! \file

 *  docs for this file

 */

 

//@{

//! one description for all members of this group

//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)

#define A 1

#define B 2

void glob_func();

//@}

Click here for the corresponding HTML documentation that is generated by Doxygen.

Here Group1 is displayed as a subsection of the "Public Members". And Group2 is a separate section because it contains members with different protection levels (i.e. public and protected).

本文地址:http://com.8s8s.com/it/it37359.htm