CSDN博客

img SigmaSys

DoxyGen文档之七

发表于2003/12/29 17:20:00  1720人阅读

第四章:Grouping归组

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

Modules模块

Modules是一种归组things在分离的page上的方式。组的成员可以是filenamespaceclassesfunctionsvariablesenumstypedefsdefines,但也可以是其他groups

 

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

 

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

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

 

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

 

/** /addtogroup <label> */

/*/@{*/

/*/@}*/

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

 

注意compound entities(例如classesfilesnamespaces)可以放在多个groups中,但是members(例如variablesfunctionstypedefsenmus)只可以归于一个group(这个限制是为了避免链接目标的ambiguous)。

 

Doxygenmembers放在有最高优先级的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已经做了groupmember 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(例如一个classfile)有多个members,通常我们希望将其groupDoxygen已经可以自动按照类型和protection级别将这些things归组在一起,但可能你会认为仅仅这样是不够的或者这种缺省的方法是错误的。例如你认为有不同(语法)的类型需要归入同一个group(语意)。

这样定义一个member group

//@{

  ...

//@}

块或者使用

/*@{*/

  ...

/*@}*/

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

 

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

 

Member groups不允许使用嵌套。

如果一个类中的某个member group中所有的members有相同的typeprotection level(例如都是static public members),那么这整个都会作为该type/protection level groupsubgroup显式出来(例如,这个group作为“static public memberssectionsubsection)。如果两个或更多成员有不同的类型,那么这个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).

阅读全文
0 0

相关文章推荐

img
取 消
img