前言

下面主要讲解linux下Doxygen命令行实现html文档生成的操作，当然也有界面版本操作方式，linux下安装doxygen-gui即可通过doxywizard开启界面操作，windows下也可以通过doxywizard.exe界面进行配置操作，具体的界面操作请参考其他网上文章，不过有一句话需要说明：会命令行操作的，应该都会界面操作，而会界面操作的就不一定会命令行操作了。

windows下的操作方式可以参考 使用doxygen生成chm范例

doxygen是什么

按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处：

便于代码和文档保持同步

可以对文档做版本管理

Doxygen就是这样的工具，Doxygen是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。很多编程语言都有类似的文档工具，例如：Java有javadoc，Ruby有rdoc。对于C/C++程序，我们可以用Doxygen生成文档。Doxygen有如下特点：

支持的编程语言：完全支持 C、C++、Java、IDL、Objective-C、Python、PHP、C#、Fortran、VHDL

输出格式：直接支持 HTML、Latex、RTF、manpage、Qt help project、XML，间接支持 chm、

Qt Compressed Help、Postcript和PDF；

兼容 JavaDoc、Qt-Doc、KDOC等类似工具；

支持平台：Unix(包括Linux)、MacOs、Windows等；

主页：http://www.doxygen.org/

邮件列表：

doxygen-user@lists.sourceforge.net

doxygen-develop@lists.sourceforge.net

作者：Dimitri van Heesch (dimitri@stack.nl) ；

Doxygen基本操作流程

按照Doxygen的约定，将代码“文档化”。这部分请参考 代码‘文档化’；

编写一个配置文件(Doxyfile)，用于配合Doxygen生成最终的文档。这部分请参考 编写一个Doxygen配置文件；

执行doxygen Doxyfile生成文档。

下面详细介绍每一个步骤。

代码‘文档化’

这一部分需要了解基本的注释规则和doxygen注释标记

doxygen注释规则

并非所有程序代码中的注释都会被 Doxygen 处理(除非在配置文件里使能了EXTRACT_ALL等选项)，必需依照正确的格式撰写，Doxygen 可处理下面两种类型的注解(注意：默认采用的JavaDoc风格，你也可以选择采用Qt或者c/c++风格),如下:

/**

* ...多行注释...

*

*/

/** ...单行注释... */

由于 Doxygen 认为注释是说明它下面的程序代码。所以,如果注释要与前面的程序码在同一行内,则需用下面这种型式的注释:

/**< ...代码同行情况的注释 */

注意,除**后多了一个

首先,我们先说明在 Doxygen 中对於类别或是函数注解的一个特定格式。

/**

*

* struct、class、functiond的简易说明...

*

* struct、class、functiond的详细说明...

* ...

*/

上面这个例子要说的是,在 Doxygen 处理一个类定义或是函数定义之上的注释时:

会先判断第一行为简易说明,这个简易说明将一直到遇见一个空白行的出现或是遇到第一个 . 为止;

之后的注解将会被视为详细说明。

另一种比较清楚的方式是指定@brief 的指令,这将会明确的告诉 Doxygen 哪个是简易说明。

doxygen在处理注释文档的时候，会进行如下的过程：

执行在文档中的特殊命令。命令都以''或'@'开始,二者是一样的，都是为了引出一个命令。例如'\brief','\details','@brief', '@details'等等。

如果一行以空白开始，后面跟着一个或者多个''，然后又跟着0个或者多个空白，那么所有的空白和''将会被移除。

所有的空行将会被当作段分隔符号。

为相应的被文档化了的类的单词创建相应的链接(除非这个单词前面放置一个'%'，这时候就没有链接了并且'%'也会被移走了)。

如果在文本中发现了相应的匹配，会建立成员的链接。(?)

文档中的HTML标记会被解释、转化为LATEX的东西以便成为LATEX的输出。(?)

Doxygen常用的代码注释标记

文件信息

@file 文件名(遵守文件命名规则) --> 文件声明，即当前文件名

@author 作者名 --> 作者

@version 版本号 --> 版本号

@todo 说明文字 --> TODO 列表，在相关页面有它专门一项

注:只能在实现文件(.c/.cpp)中使用，如果相同函数的实现文件与头文件中均有，生成的文档中会有重复项，可以理解为调用者不应知道实现流程

@date 日期时间 --> 说明文件生成的日期时间

@section 章节标题 --> @section LICENSE 版权许可 @section DESCRIPTION 描述

模块信息

@defgroup 模块名(英文) 显示名(中文) @{ 类/函数/变量/宏/... @}--> 定义模块

@ingroup 模块名(英文) [显示名(中文)]--> 作为指定名的模块的子模块,显示名为可选项,可与指定名的模块的显示名不同

@addtogroup 模块名(英文) [显示名(中文)] --> 作为指定名的模块的成员,显示名为可选项,必需与指定名的模块的显示名相同

@name 显示名(中文) @{ 变量/宏 @} --> 按用途分,以便理解全局变量/宏的用途

这部分推荐参考： doxygen使用总结

函数信息

@param 参数名 说明文字 --> 不建议使用这个

@param[in] 参数名 说明文字 --> 输入参数

@param[out] 参数名 说明文字 --> 输出参数

@param[in,out] 参数名 说明文字 --> 即输入又输出参数

@exception 用来说明异常类及抛出条件

@remark 表示评论，暴露给客户程序员的文档

@return 说明文字 --> 返回值说明

@retval 说明文字 --> 特定返回值说明

@note 说明文字 --> 注解,可以描述工作流程和注意事项

@par [段落标题] --> 开创新段落,一般与示例代码联用

@code --> 示例代码开始

@endcode --> 示例代码结束

@see 类/函数/变量/文件/URL --> 参见,

类名::函数名 或 ::函数名 可以变成超链接点击跳转到对应函数说明处

函数重载的情况下,要带上参数列表以及返回值

@deprecated 说明文字 --> 过时列表,在相关页面有它专门一项

注:只能在头文件(*.h)中使用,如果相同函数的实现文件与头文件中均有,

生成的文档中会有重复项,可以理解为维护者不关心这个接口是不是要过时

@pre 说明文字 --> 前置条件

@arg 参数/返回值 说明文字 --> 以列表形式说明参数取值意义

注:也可以用 - 或 -# 来代替,建议此种方法,简单明了

- 第一级

- 第二级

- 第三级

即相同开头的-或 -#第二行比第一行缩进一个英文空格就变了第二级,依次类推

- 开头的第一级为实心黑圆点;第二级为空心黑圆点;第三级以后为实心方块;

-#开头的第一级为数字(1./2./3./...),

第二级为小写字母(a./b./c./...),

第三级为罗马数字(i./ii./iii./...),

第四级为大写字母(A./B./C./...)

提醒信息

@brief 说明文字 --> 摘要,即当前文件/函数说明

@attention 说明文字 --> 注意

@bug 说明文字 --> 问题

@warning 说明文字 --> 警告

@ref 引用其他标记，类似于html中的锚

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

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

@def 宏定义说明

@fn 函数 函数说明

@test 测试示例、信息

(@bug、@test以及@todo等会出现链接页面)

下面为生成特殊字体的命令：

@a @e @em：其后的单个字(word)表现为斜体，以强调作用。如有多个word的话，使用xxx xxx代替

@b：其后的word为粗体，多个则使用xxx xxx

@c @p：字体表现为打印机字体，多个则使用xxx xxx

@enum 引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum

@var 引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey

@class 引用某个类，格式：@class [] [] eg:@class CTest "inc/class.h"

下面举例说明可能遇到的几种情况：

文件注释

/**

* @file

* @author rongp

* @version 1.0.0

* @date 2016/02/22

*

* @section LICENSE

*

* Copyright(c) 2015-2020 XXX

* All rights reserved

*

* @brief iss服务器端sdk导出根文件

*

* @section DESCRIPTION

* 界面开发者只需要包含该头文件即可, 具体的导出数据结构、api分别分别在

* net_io_export.h和app_amp_export.h中

*

*/

函数注释

/**

* @brief 创建与本地服务通讯的端点

* @param[in] proto_type 端点通讯采用的协议类型, 一般设置为PROTO_TYPE_TRANS即可

*

* @return 用于通讯的端点指针，作为后面接口的参数

* @retval non-NULL 成功

* @retval NULL 出错

*

* @warning 该接口只能在服务端sdk使用, 当前只支持PROTO_TYPE_TRANS协议类型

*

* 示例

@code

gpointer e = net_io_create_local_endpoint(PROTO_TYPE_TRANS);

@endcode

*

* @since 1.0.0

*/

结构体注释

/**

* @brief 服务器信息描述结构

*/

struct _ServerInfo {

/** 服务器系统版本, 包括硬件信息、操作系统信息等 */

gchar sys_ver[128];

/** 服务器软件版本 */

gchar soft_ver[128];

};

枚举注释

/**

* @brief 消息返回码

*/

enum MSG_RET_CODE {

/** 执行成功 */

MSG_EXECUTE_OK = 0,

/** 超时 */

MSG_TIMEOUT = -1,

/** 消息的大小有误 */

MSG_SIZE_UNMATCH = -2,

/** 不允许执行该消息 */

MSG_OPT_FORBID = -3,

/** 服务器端服务出错 */

MSG_SYSTEM_ERR = -4,

/** 消息的参数有误 */

MSG_ARG_INVALID = -5,

/** buf内存不够 */

MSG_NOMEM = -100,

};

编写一个Doxygen配置文件

一般是通过先生成模板配置文件，然后基于模板配置文件修改即可。使用 "doxygen -g" 命令在当前目录下生成名为‘Doxyfile’的配置文件模板。也可以采用 "doxygen -g filename" 命令格式指定所生成的配置文件名为filename。如无特殊需要，采用默认的配置文件名即可。如果对 Doxygen 各配置选项的意义有一定了解，可以在生成配置文件的命令中添加 "-s" 选项，生成不含注释的配置文件，如:doxygen -s -g 这种方式生成的配置文件非常精简，没有任何注释。

有了doxygen模板配置文件后，现在要做的就是对它进行修改了，下面以c语言开发的项目生成html为例。主要有下面几个选项需要修改：

# 项目名称，将作为于所生成的程序文档首页标题，需要使用双引号括住

PROJECT_NAME = “xxx”

# 文档版本号，可对应于项目版本号，譬如 git、svn、cvs 所生成的项目版本号

PROJECT_NUMBER = “1.0.0”

# 程序文档输出目录，产生的文件会放在这个路径之下。如果没有填这个路径，将会以当前所在路径来作为输出路径。

OUTPUT_DIRECTORY = doc/

# 程序文档语言环境，预设为 English。1.2.16 版后，可以用 Chinese 输出简体中文，也可以使用

# Chinese-Traditional 来输出中文繁体的格式。

OUTPUT_LANGUAGE = Chinese

# 如果是制作 C 程序文档，该选项必须设为YES，否则默认生成 C++ 文档格式

OPTIMIZE_OUTPUT_FOR_C = YES

# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化

TYPEDEF_HIDES_STRUCT = YES

# 把这个标记设置为Yes，即使各个类或函数没有文档，也要提取信息

EXTRACT_ALL = YES

# 把这个标记设置为Yes，文档就会包含类的私有数据成员

EXTRACT_PRIVATE = YES

# 把这个标记设置为Yes，文档就会包含文件的静态成员(函数和变量)

EXTRACT_STATIC = YES

# 在 C++ 程序文档中,该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字空间

# 这样的概念，所以此处设置为 YES

HIDE_SCOPE_NAMES = YES

# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息

QUIET = YES

# 这个标记创建一个以空格分隔的所有目录的列表，

# 这个列表包含需要生成文档的 C/C++ 源代码文件和头文件，可以不设定，即为当前目录!

INPUT = inc/

# 输入文件的编码格式，需要自己根据INPUT指定的文件选择，否则会乱码

INPUT_ENCODING = UTF-8

# 在默认情况下,doxygen 会搜索具有典型 C/C++ 扩展名的文件，

# 比如 .c、.cc、.cpp、.h 和 .hpp 。

# 可以使用如下形式的列表方式,指定INPUT下要处理的文件

# 注:文件类型后有空格然后是右斜杠然后回车,每一个文件类均独自一行!

# FILE_PATTERNS = *.h \

*.c \

*.cpp

FILE_PATTERNS =

# 递归遍历由 INPUT 所指定的目录及其所有子目录，寻找由 FILE_PATTERNS 指定的要被文档化的文件

RECURSIVE = YES

# 如果您有特定文件或目录，不希望经过 Doxygen 处理，那你可在这指出，没有就不指出

# 例如:EXCLUDE = /home/xxx/src_root /home/xxx/test

EXCLUDE =

# 类似于 FILE_PATTERNS 的用法，只是这个是供 EXCLUDE 所使用

EXCLUDE_PATTERNS =

# 若设定为 YES，就会产生 HTML 版本的说明文件。HTML 文件是 Doxygen 预设产生的格式之一

GENERATE_HTML = YES

# 若设定为 YES，Doxygen 会帮您产生一个树状结构，在页面左侧，默认为 NO

# 这个树状结构是以 JavaScript 所写成。所以需要新版的 Browser 才能正确显示。

GENERATE_TREEVIEW = YES

其他可参考的：

文档输出格式

除了 HTML 之外，doxygen 还可以生成几种输出格式的文档。可以让 doxygen 生成以下格式的文档：

UNIX 手册页：把 标记设置为 Yes。在默认情况下，会在 指定的目录中创建 man 子文件夹，生成的文档放在这个文件夹中。必须把这个文件夹添加到 MANPATH 环境变量中。

Rich Text Format(RTF)：把 标记设置为 Yes。把 标记设置为希望放置 .rtf 文件的目录；在默认情况下，文档放在 OUTPUT_DIRECTORY 中的 rtf 子文件夹中。要想支持跨文档浏览，应该把 标记设置为 Yes。如果设置这个标记，生成的 .rtf 文件会包含跨文档链接。

Latex：在默认情况下，doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中， 标记设置为 Yes。另外， 标记设置为 Latex，这意味着会在 OUTPUT_DIRECTORY 中创建 latex 子文件夹并在其中生成 Latex 文件。

Microsoft® Compiled HTML Help(CHM)格式：把 标记设置为 Yes。因为在 UNIX 平台上不支持这种格式，doxygen 只在保存 HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。

Extensible Markup Language(XML)格式：把 标记设置为 Yes。(注意，doxygen 开发团队还在开发 XML 输出)。

按照上面的修改后，就可以执行第三步，执行命令doxygen Doxyfile生成文档了。注意：这里的Doxyfile

为你实际的Doxygen配置文件名。

Doxygen与其他工具配合生成chm

Doxygen FAQ

6.1 中文问题：中文注释在文档中是乱码

解决：在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。

6.2 图形问题：无法绘制类图协作图等图形。

解决：首先确保安装了graphviz for win，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。

如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。

6.3 输出chm的问题：如何输出.chm文件

配置时注意expert中的HTML页：选中“GENERATE_HTMLHELP”，然后在CHM_FILE中填上想要的chm文件名。

HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。

或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件，编译完成后即可在该html文件夹中找到对应的chm文件

6.4 Doxygen无法为DLL中定义的类 导出文档

例如：

class __declspec(dllexport) CClassName:public CObject

{

}

目前发现Doxygen无法识别出DLL中定义的类。

http://ticktick.blog.51cto.com/823160/188674

未完，待续

2016年6月