doxygen配置及使用手册

Doxygen安装及使用手册

一简介

Doxygen可以从C，C++，java等源代码中提取消息来生成帮助文档，API资料等

二下载Doxygen

以下，是在linux平台下的demo介绍。

http://www.stack.nl/~dimitri/doxygen/index.html

doxyen主页去下载doxygen-1.5.5.src.tar.gz

三 Doxygen安装

安装doxygen-1.5.5.src.tar.gz

1 把下载好的doxygen-1.5.5.src.tar.gz拷到自己想要的目录中，我放到了自己的Home目录下。

2 进入相应的目录：本例是在自己的home目录下

3 解压

#tar -zxvf doxygen-1.5.5.src.tar.gz会在当前目录下生成一个名字为doxygen-1.5.5的目录。

4 在自己的Home目录下建立一个doxygen目录，我们的doxygen以后就安装到这个目录下。#mkdir doxygen

5 进入doxygen-1.5.5目录

#cd doxygen-1.5.5

6 安装：用—prefix选项制定安装目录为/home/lvq/doxygen，lvq为我的用户名，这里可以用~/doxygen代替。

#./configure –prefix ~/doxygen

#make

#make install

这样在~/doxygen 目录就安装好了doxygen软件

7 生成配置文件

#cd ~/doxygen/bin/

# ./doxygen –g 文件名

执行这个命令后就会生成一个制定名字的配置文件，这里我们不加文件名，只用./doxygen –g 生成默认配置文件Doxyfile。

四如何使用Doxygen

Doxygen可以从源代码中提取消息生成帮助文档，它是根据源代码中的特定注释来实现。所以，首先要给工程代码书写符合Doxygen格式的注释。

1 以sipproxy小工程为例

1)这个工程在/home/lvq/self/sipproxy1/sipproxy-v1.04/目录下。这个代码是用C语言

实现的。

其中的多行注释形式为/** …*/，单行注释为///，对于其他语言注释形式略有不同。

2)以一个函数为例，说明如何书写注释

/**

* @brief process the received sip message, then send it to the remote client. * @param buf a received sip message buffer.

* @retval return TRUE if it successes, else return FALSE.

*/

int udp_process_message(char *precvstr)

3)因为一般一个工程项目中有很多模块，所以按模块分类显示效果会更好些。要生成模块

需要特定的注释。以sipproxy为例，其中在sipproxy-v1.04/目录下又有两个子目录：layer2和layer3。Layer2/下面有main.c,file.c,file.h三个文件，layer3/下面有socket.c,socket.h两个文件。我们根据目录名生成两个模块。

要实现这个功能，就要借助于注释格式@defgroup，用它可以给源代码生成一个模块名.如下：

在main.c中，用/** @defgroup Layer2 */定义一个模块分组Layer2，再把其他两个文件file.c和file.h加入到这个分组中，可以用/** @weakgroup File @ingroup Layer2 */说明包含在Layer2模块中，//@{ 和 //@}对把要包含的代码加到这个分组中。

用同样的方法给Layer3分组。

2 配置文件Doxyfile

Siproxy工程中的源代码已经注释好，但还必须合理配置文件Doxyfile（在安装的时候已经说明怎么生成此配置文件）。这里只配置需要的配置选项，其他配置选项，使用者可以根据自己的需要进行配置。

#vi ~/doxygen/bin/Doxyfile

PROJECT_NAME = Sip Proxy （项目名称）

PROJECT_NUMBER = 1.0 （相当于版本号）

OUTPUT_DIRECTORY = /home/lvq/outputdoxygen (事先建好的目录，生成的帮助文档就在这个目录下，要用绝对路径)

CREATE_SUBDIRS = YES (如果此项设成YES将会产生4096个子目录，可根据需要选择配置与否)

OUTPUT_LANGUAGE = English (生成英文版文档)

OPTIMIZE_OUTPUT_FOR_C = YES （C语言源代码程序专用）

EXTRACT_ALL = YES

SHOW_DIRECTORIES = YES （这样将展现路径层次）

INPUT = /home/lvq/self/sipproxy1/sipproxy-v1.04/ (源代码所在路径)

RECURSIVE = YES （搜索子目录）

EXCLUDE = lib include （制定不搜索的子目录）

EXCLUDE_PATTERNS = */lib/* */include/* （不分析这两个目录下的文件） SOURCE_BROWSER = NO （此项设置NO,将不包含源代码）

GENERATE_TREEVIEW = YES （生成一个树状结构）

PDF_HYPERLINKS = YES （生成PDF文件）

USE_PDFLATEX = YES

配好之后，保存退出：按shift键 :（冒号）wq

3) 执行

#./doxygen Doxyfile

执行成功后在outputdoxygen目录下生成两个目录：html和latex

4) 如果想生成PDF格式文件则进入outputdoxygen/latex下执行make命令：

#cd ~/outputdoxygen/latex

#make

执行成功之后将生成PDF文件。

5) 进入html目录，点击index.html，在浏览器上就会看到帮助文档。

五 Doxygen配置知识扩展

1 进入doxygen安装目录

#cd ~/doxygen

2 进入doxygen下的bin/目录

#cd bin/

3 生成先doxygen -g来生成一个Doxygen配置文件,在该配置文件里设置一些选项，doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释'#'开始；tag = value [,value2…]；对于多值的情况可以使用tag += value [,value2…]。

对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。

下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。

TAG 缺省值含义

PROJECT_NAME 项目名称(我的例子项目名称为sipproxy)

PROJECT_NUMBER 可以理解为版本信息(1.0)

OUTPUT_DIRECTORY 输出文件到的目录，相对目录（doxygen运行目录）或者

绝对目录(~/outputdoxygen)

INPUT 代码文件或者代码所在目录，使用空格分割

FILE_PA TTERNS *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh

*.hxx *.hpp *.h++ *.idl *.odl 指定INPUT的目录中特定文件，如：*.cpp *.c *.h

RECURSIVE NO 是否递归INPUT中目录的子目录

EXCLUDE 在INPUT目录中需要忽略的子目录(这里排除lib和include目录，填写：lib include)

EXCLUDE_PATTERNS 明确指定的在INPUT目录中需要忽略的文件，如：

*/include/* */lib/*

OUTPUT_LANGUAGE English 生成文档的语言，当前支持2、30种语言，国内用

户可以设置为Chinese

USE_WINDOWS_ENCODING YES（win版本）

NO（unix版本）编码格式，默认即可。

EXTRACT_ALL NO 为NO，只解释有doxygen格式注释的代码；为YES，解析所

有代码，即使没有注释。类的私有成员和所有的静态项由EXTRACT_PRIV ATE和

EXTRACT_STA TIC控制

EXTRACT_PRIV A TE NO 是否解析类的私有成员

EXTRACT_STA TIC NO 是否解析静态项

EXTRACT_LOCAL_CLASSES YES 是否解析源文件（cpp文件）中定义的类

SOURCE_BROWSER NO 如果为YES，源代码文件会被包含在文档中

INLINE_SOURCES NO 如果为YES，函数和类的实现代码被包含在文档中

PDF_HYPERLINKS 标志设置成YES, 想生成PDF文件

ALPHABETICAL_INDEX NO 生成一个字母序的列表，有很多类、结构等项时建

议设为YES

GENERATE_HTML YES 是否生成HTML格式文档

GENERATE_HTMLHELP NO 是否生成压缩HTML格式文档（.chm）

GENERATE_LATEX YES 是否乘车latex格式的文档

GENERATE_RTF NO 是否生成RTF格式的文档

GENERATE_MAN NO 是否生成man格式文档

GENERATE_XML NO 是否生成XML格式文档

六Doxygen注释知识扩展

1 doxygen注释

1.1 注释风格

下面是工作量最大部分，安装doxygen格式写注释。通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两部分都是可选的。可以有多种方式标识出doxygen 可识别的注释块。

1）JavaDoc类型的多行注释。

/**

* ….text….

*/

2）QT样式的多行注释。

/*!

….text….

*/

3）/// …text….

4）//! …text….

简要说明有多种方式标识，这里推荐使用@brief命令强制说明，例如：

/**

* @brief [some brief description ]

* [ brief description more. ]

*

* [some more detailed description…]

*/

以上这些注释格式用来对紧跟其后的代码进行注释。doxygen也允许把注释放到代码后面，具体格式是放一个'<'到注释开始部分。例如：

int var1 ; /**< ….text…. */

int var2; ///< ….text….

注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。

1.2 doxygen常用注释格式

通常的选择上面的一、两种注释风格，遇到头文件中各种类型定义，关键变量、宏的定义，在其前或者后使用@brief 定义其简要说明，空一行后继续写其详细的注释即可。

对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下：/**

*@brief func's brief comment.

*

* Some detailed comment.

*@param a [param a 's comment.]

*@param b [param b 's comment.]

*@exception std::out_of_range [exception's comment.]

*@return [return's comment.]

*/

int func1(int a, int b);

进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。

/** [group_name] [brief group description ]

* detailed group description ]

* @{

*/

code

/** @} */

group中的代码可以有自己的注释。单纯定义一个模块，去除{ 和}命令即可。任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup 命令即可。Group之间使用ingroup命令，可以组成树状关系。

/** @file util.cpp

* @ingroup [group_name]

* @brief file's brief info.

*/

把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。

对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：

//@{

/** Comments for all below code. */

code…

//@}

对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：

/** @name group_name

* description for group.

*/

//@{

code…

//@}

1.3 doxygen常用注释命令

doxygen通过注释命令识别注释中需要特殊处理的注释，比如函数的参数、返回值进行突出显示。上面也提到了一些注释命令（如：brief、param、return、以及group相关的命令），下面对其他一些常用的注释命令进行解释说明。

@exception {exception description} 对一个异常对象进行注释。

@warning {warning message } 一些需要注意的事情

@todo { things to be done } 对将要做的事情进行注释

@see {comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。

@relates 通常用做把非成员函数的注释文档包含在类的说明文档中。

@since {text} 通常用来说明从什么版本、时间写此部分代码。

@deprecated

@pre { description of the precondition } 用来说明代码项的前提条件。

@post { description of the postcondition } 用来说明代码项之后的使用条件。

@code 在注释中开始说明一段代码，直到@endcode命令。

@endcode 注释中代码段的结束。

到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。

1.4 注释的书写

注释应该怎么写，写多还是写少。过多的注释甚至会干扰对代码的阅读。写注释的一个总的原则就是注释应该尽量用来表明作者的意图，至少也应该是对一部分代码的总结，而不应该是对代码的重复或者解释。对代码的重复或者解释的代码，看代码可能更容易理解。反映作者意图的注释解释代码的目的，从解决问题的层次上进行注释，而代码总结性注释则是从问题的解答的层次上进行注释。

推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点：

避免对单独语句进行注释；

通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；

对读者可能会有疑问的地方进行注释；

对数据定义进行注释，而不是对其使用过程进行注释；

对于难于理解的代码，进行改写，而不要试图通过注释加以说明；

对关键的控制结构进行注释；

对数据和函数的边界、使用前提等进行注释；

1.5Modules模块

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 */

/*\@{*/

/*\@}*/

这样可以在其他地方以更加详细的说明添加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).

(本文档仅供参考，错误的地方请使用者更正，并不断使之完善)