Linux下Doxgen的安装与使用-优快云博客

Linux下Doxgen的安装与使用

软件平台：运行于VMware Workstation 12 Player下UbuntuLTS16.04_x64 系统
参考资料：【Doxgen的注释】、【才鲸 / 嵌入式编程技巧】
开发环境：Linux 3.4.2内核、arm-linux-gcc 4.3.2工具链

一、安装

1、网络安装

直接执行sudo apt-get install doxgen

2、压缩包安装

在官网下载doxygen-1.8.18.linux.bin.tar.gz压缩包，通过软件上传压缩包到Linux系统后，执行以下命令：

sudo tar xvfz doxygen-1.8.18.linux.bin.tar.gz
cd doxygen-1.8.18/
./configure
make
sudo make install

二、使用

针对C语言语法，也适用于C++

1、注释

头文件注释

/** @brief   摘要
 *  @file    文件名
 *  @author  作者
 *  @version 版本
 *  @date    日期
 *  @note    注解. 例如: 本文件有什么具体功能啊, 使用时要注意什么啊..
 *  @since   自从...
 */

函数注释

/**  函数的概述
 * @param[in]  输入参数1
 * @param[in]  输入参数2
 * @param[out] 输出参数1
 * @return     返回值解释一下
 * @warning    警告: 例如: 参数不能为空之类的
 * @note       注解
 * @see        类似于请参考xxoo函数之类的
 * @todo       可描述算法比较好
 * @exception  函数抛出异常
 */

返回值也可以这样写：

@retval 1 成功
@retval 0 失败

块注释模板

/*---第一种（比较常用）---*/
/**
 * ... text ...
 */

/*---第二种（比较常用）---*/
/*!
 * ... text ...
 */
 
/*---第三种（比较显眼）---*/
/********************************************//**
 * ... text
 ***********************************************/

/*---第四种（比较显眼）---*/
/************************************************
 * ... text
 ***********************************************/

变量注释注释

/*---第一种（详细描述）---*/
int var; /**< Detailed description after the member */

/*---第二种（简要描述）---*/
int var; //!< Brief description after the member

/*---第三种（简要描述）---*/
int var; ///< Brief description after the member

常用关键字

@author     作者的信息
@brief      用于class 或function的简易说明 eg：@brief 本函数负责打印错误信息串
@bug        被标记的代码会在Bug列表中出现
@class      类名
@date       日期
@file       文件名，可以默认为空，DoxyGen会自己加
@param      主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return     描述该函数的返回值情况eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval     描述返回值类型 eg: @retval NULL 空字符串。@retval !NULL 非空字符串。
@note       注解
@attention  注意
@name       分组名
@warning    警告信息
@enum       引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum
@var        引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey
@class      引用某个类，格式：@class <name> [<header-file>] [<header-name>] eg:@class CTest "inc/class.h"
@exception  可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo       对将要做的事情进行注释
@see        see also字段
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since      从哪个版本后开始有这个函数的
@code       在注释中开始说明一段代码，直到@endcode命令。
@endcode    在注释中代码段的结束。
@remarks    备注
@pre        用来说明代码项的前提条件。
@post       用来说明代码项之后的使用条件。
@deprecated 这个函数可能会在将来的版本中取消。
@defgroup   模块名
@{
             模块开始
@}          模块结束
@class      声明一个类 
@version    版本号
@fn         声明一个函数
@par        开始一个段落，段落名称描述由你自己指定，比如可以写一段示例代码
-           一级项目符号
-#          二级项目符号

2、配置文件与说明文件的生成

2.1 采用官方默认配置文件

安装好Doxgen后，在需要生成说明文件的工程目录中

执行doxgen -g，此时会在该目录下生成Doxyfile默认配置文件（具体代码如下所示）；
执行doxgen，此时会按照配置文件中的信息生成说明文件（html、latex格式）；
执行firefox +所在目录/index.html，此时就会打开说明文件的html版本。

2.2 自定义配置文件

根据官方的说明文档自己编写配置参数，下面的配置文件是比较通用的（出自：https://gitee.com/langcai1943/embedded_programming_skills/tree/develop/）

假设自定义配置文件名为Doxyfile1，则生成说明文件执行doxgen Doxyfile1
即doxgen + 自定义配置文件名
执行firefox +所在目录/index.html，此时就会打开说明文件的html版本。

使用中常修改的参数

# 生成文档的标题首页名称
PROJECT_NAME           = "标题名"

# 文档版本号
PROJECT_NUMBER         = "版本数字"

# 生成文档的路径，为相对路径
# out/表示：当前配置文件所在目录的out目录
OUTPUT_DIRECTORY       = out/

# 输出文档的语言，可以选择多种，具体可以参考官方文档
OUTPUT_LANGUAGE        = Chinese

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

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

# 把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。
EXTRACT_STATIC         = YES

############################################
# 当需要指定文件生成说明文件
# 1、指定文件
#	设置FILE_PATTERNS = 指定文件名
# 2、指定所在目录文件
#   INPUT  = 目录名
#	FILE_PATTERNS = 指定文件名
############################################

# 在这里，doxygen 会从这两个目录读取 C/C&