DoxyGen文档之七

原创 2003年12月29日 17:20:00

第四章:Grouping归组<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />

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).

转载:DoxyGen文档之七

第四章:Grouping归组Doxygen有两种机制进行归组。第一种是全局级,为每个group创建一个新的page。这些groups在注释中被称作“modules”。另一种机制使用于一些compoun...
  • prophet08
  • prophet08
  • 2007年04月06日 19:32
  • 718

如何用doxygen生成文档

Doxygen是一款基于源代码生成文档的工具,类似于Java中的javadoc. 概念:文档和注释的区别 文档(Documentation) 是给代码的使用者准备的,或者是更高一级的开发...
  • hitlion2008
  • hitlion2008
  • 2013年03月07日 21:05
  • 8451

使用Doxygen生成全中文的chm帮助文档

下载和安装 Doxygen到 Doxygen 官网 下载最新的Doxygen安装程序,然后安装。这个软件包包括了一个GUI界面的前端工具,可以帮助我们方便创建Doxygen配置文件和生成目标文档。下...
  • xzytl60937234
  • xzytl60937234
  • 2017年04月22日 15:55
  • 805

doxygen生成word文档

doxygen生成rtf/word使用小心得2009-07-26 19:53       硕士毕业要写个技术文档,蒙了,真麻。怎么也都不行,后来老师给指了条路:使用doxygen。      网上有许...
  • jiabin_007
  • jiabin_007
  • 2010年01月19日 17:37
  • 1514

使用doxygen生成注释文档——visual studio

前期准备:代码注释。 这里介绍两个方法: 一.安装插件 1. 安装GhostDoc插件。(建议设置快捷键为shift+Alt+j) 2. 回到vs界面规范注释规则。 Tools->GhostDoc->...
  • index_cqq
  • index_cqq
  • 2016年03月22日 16:48
  • 2343

用 Doxygen 自动生成文档

              用 Doxygen 自动生成文档             Horin|贺勤        Email: horin153@msn.com        Blog: http...
  • horin153
  • horin153
  • 2007年04月30日 15:09
  • 6409

用doxygen生成中英文帮助

来源:http://www.opencv.org.cn/forum/viewtopic.php?f=1&t=2635#p9188 用doxygen生成中英文帮助由 chai2010 于 2008-02...
  • hitxiaya
  • hitxiaya
  • 2010年11月26日 13:52
  • 765

利用doxygen生成python文档

On and off I have been developing a little Python module to provide KP-ABE and CP-ABE functionality ...
  • carolzhang8406
  • carolzhang8406
  • 2015年11月09日 14:22
  • 1568

Doxygen生成注释文档

概述:  Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、Objective-C和IDL语言,部分支持PHP、C#。注释的语法与Qt-Do...
  • tuwenqi2013
  • tuwenqi2013
  • 2017年04月11日 13:27
  • 1101

Doxygen自动文档生成工具在Eclipse中的集成及使用举例

你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的办...
  • lanxuezaipiao
  • lanxuezaipiao
  • 2014年02月16日 17:57
  • 4136
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:DoxyGen文档之七
举报原因:
原因补充:

(最多只允许输入30个字)