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月


    毕业那两年在做嵌入式应用开发,主要是单片机和arm linux上的应用开发,后来又做了两年arm linux驱动开发,15年到现在在做pc端及嵌入式端开发,包括服务器系统裁剪、底层框架实现、硬件加速等。喜欢技术分享、交流!联系方式: 907882971@qq.com、rongpmcu@gmail.com

posted @ 2017-10-14 10:15  rongpmcu  阅读(7325)  评论(0编辑  收藏  举报