doxygen使用

前言

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

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

doxygen是什么

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

1. 便于代码和文档保持同步
2. 可以对文档做版本管理

　　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基本操作流程

1. 按照Doxygen的约定，将代码“文档化”。这部分请参考 代码‘文档化’；
2. 编写一个配置文件（Doxyfile），用于配合Doxygen生成最终的文档。这部分请参考 编写一个Doxygen配置文件；
3. 执行doxygen Doxyfile生成文档。

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

代码‘文档化’

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

doxygen注释规则

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

/**
 *  ...多行注释...
 *
 */

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

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

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

注意,除**后多了一个<,其它的与前面相同。

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

/**
 *
 * struct、class、functiond的简易说明...
 *
 * struct、class、functiond的详细说明...
 * ...
 */

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

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

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

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

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

1. 执行在文档中的特殊命令。命令都以''或'@'开始,二者是一样的，都是为了引出一个命令。例如'\brief','\details','@brief', '@details'等等。
2. 如果一行以空白开始，后面跟着一个或者多个''，然后又跟着0个或者多个空白，那么所有的空白和''将会被移除。
3. 所有的空行将会被当作段分隔符号。
4. 为相应的被文档化了的类的单词创建相应的链接（除非这个单词前面放置一个'%'，这时候就没有链接了并且'%'也会被移走了）。
5. 如果在文本中发现了相应的匹配，会建立成员的链接。(?)
6. 文档中的HTML标记会被解释、转化为LATEX的东西以便成为LATEX的输出。(?)

Doxygen常用的代码注释标记

1. 文件信息
   
   @file 文件名(遵守文件命名规则) --> 文件声明，即当前文件名
   
   @author 作者名 --> 作者
   
   @version 版本号 --> 版本号
   
   @todo 说明文字 --> TODO 列表，在相关页面有它专门一项
   
   注:只能在实现文件(.c/.cpp)中使用，如果相同函数的实现文件与头文件中均有，生成的文档中会有重复项，可以理解为调用者不应知道实现流程
   
   @date 日期时间 --> 说明文件生成的日期时间
   
   @section 章节标题 --> @section LICENSE 版权许可 @section DESCRIPTION 描述
2. 模块信息
   
   @defgroup 模块名(英文) 显示名(中文) @{ 类/函数/变量/宏/... @}--> 定义模块
   
   @ingroup 模块名(英文) [显示名(中文)]--> 作为指定名的模块的子模块,显示名为可选项,可与指定名的模块的显示名不同
   
   @addtogroup 模块名(英文) [显示名(中文)] --> 作为指定名的模块的成员,显示名为可选项,必需与指定名的模块的显示名相同
   
   @name 显示名(中文) @{ 变量/宏 @} --> 按用途分,以便理解全局变量/宏的用途
   
   这部分推荐参考： doxygen使用总结
3. 函数信息
   
   @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./...)
4. 提醒信息
   
   @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"

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

1. 文件注释

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

1. 函数注释

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

1. 结构体注释

/**
 * @brief 服务器信息描述结构
 */
struct _ServerInfo {
    /** 服务器系统版本, 包括硬件信息、操作系统信息等 */
    gchar sys_ver[128];
    /** 服务器软件版本 */
    gchar soft_ver[128];
};

1. 枚举注释

/**
 * @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 手册页：把 <GENERATE_MAN> 标记设置为 Yes。在默认情况下，会在 <OUTPUT_DIRECTORY> 指定的目录中创建 man 子文件夹，生成的文档放在这个文件夹中。必须把这个文件夹添加到 MANPATH 环境变量中。
    Rich Text Format（RTF）：把 <GENERATE_RTF> 标记设置为 Yes。把 <RTF_OUTPUT> 标记设置为希望放置 .rtf 文件的目录；在默认情况下，文档放在 OUTPUT_DIRECTORY 中的 rtf 子文件夹中。要想支持跨文档浏览，应该把 <RTF_HYPERLINKS> 标记设置为 Yes。如果设置这个标记，生成的 .rtf 文件会包含跨文档链接。
    Latex：在默认情况下，doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中，<GENERATE_LATEX> 标记设置为 Yes。另外，<LATEX_OUTPUT> 标记设置为 Latex，这意味着会在 OUTPUT_DIRECTORY 中创建 latex 子文件夹并在其中生成 Latex 文件。
    Microsoft® Compiled HTML Help（CHM）格式：把 <GENERATE_HTMLHELP> 标记设置为 Yes。因为在 UNIX 平台上不支持这种格式，doxygen 只在保存 HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。
    Extensible Markup Language（XML）格式：把 <GENERATE_XML> 标记设置为 Yes。（注意，doxygen 开发团队还在开发 XML 输出）。

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

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

Doxygen与其他工具配合生成chm

参考 https://stackoverflow.com/questions/23680921/generate-chm-from-doxgen-results

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

参考：

学习用 doxygen 生成源码文档

Doxygen使用指南 - Doxygen_Using_Manual.pdf

Doxygen: Main Page

Doxygen Manual: Getting started

未完，待续

2016年6月