C++ 程序文档生成器(doxygen)使用说明

news2024/11/15 4:32:24

程序文档，是每个程序员必看文档，在日常业务开发中，难免会封装一些组件。没有很好的组件文档，再好的组件都是废物，。因此大型业务中，文档和思维导图，两个都是必备！

一、注释风格
需要在c/c++代码中按照下面的风格添加注释，基本上还是很顺手的C++的注释风格主要使用下面这种样式：即在注释块开始使用三个反斜杠‘/’

1.1. 文件注释

/***************************************
* @file 文件名
* @brief 概述
*
* 详细概述
*
* @author 作者,包含email等
* @version 版本号(maj.min，主版本.分版本格式)
* @date 日期
*****************************************/

1.2. 命名空间的注释

///@brief 简单概述
///
///详细概述

1.3. 类定义注释

对需要的类增加注释，需要说明类的设计方法，类的使用指南，说明类的不变项

///@brief 简要概述
///
///详细说明
///
///使用指南设计函数调用可以@ref 函数名 用于引用其他的说明
///
///其他说明，重写父类函数加以特殊实现
///
///@invariant 类不变项，例如哪些值不会超多少多少
///
class xxx
{…};

1.4. 数据声明注释

行尾说明

Type varName;///< 说明

多行说明

/// 说明
///
///
Type varName;

1.5. 函数注释规范

///@brief 简单概述
///
///详细说明
///@param[in|out] 参数名，in，out表示输入还是输出
///@pre 前者条件
///@return 说明
///@retval 返回值 说明, 这个是可选的
///@post 说明函数完成后的世界状态

1.6. 代码标记数值规范

///@todo 将要做的代码
///@bug 表示此处的bug描述

1.7. 枚举变量的注释示例

///  颜色的枚举定义  
///  
///  该枚举定义了系统中需要用到的颜色\n  
///  可以使用该枚举作为系统中颜色的标识  
enum TEnum  
{  
  RED,      ///< 枚举，标识红色    
  BLUE,      ///< 枚举，标志蓝色    
  YELLOW     ///< 枚举，标志黄色.    
}enumVar;

附：Doxygen支持的指令

可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

常用指令介绍

@file    档案 的批注说明。
@author    作者 的信息
@brief    用于class 或function的简易说明eg：@brief 本函数负责打印错 误信息串
@param    主要 用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return    描述 该函数的返回值情况eg:@return 本函数返回执 行结果，若成功则返回TRUE，否则返回FLASE
@retval    描述 返回值类型eg:@retval NULL 空字 符串。@retval !NULL 非 空字符串。
@note    注解
@attention    注意
@warning    警告 信息
@enum    引用了某个枚举，Doxygen会在该枚举处产生一个链接eg：@enum CTest::MyEnum
@var    引用了某个变量，Doxygen会在该枚举处产生一个链接eg：@var CTest::m_FileKey
@class    引用 某个类，格式：@class [] []eg:@class CTest “inc/class.h”
@exception    可能 产生的异常描述eg:@exception 本函数 执行可能会产生超出范围的异常

==================

二、 linux下使用doxygen
我的开发环境是ubuntu，默认有doxygen 命令，如果没有可以从官网下载一个编译安装之doxygen工具的使用简单的2步就够了：

2.1. 生成默认配置文档

doxygen -s -g yourconfigname

这一条命令就可以生成一个叫 “yourconfigname” 的配置文档

接下来需要打开这个文档，对其中某些字段做配置，一般来说，只需要配置其中十几个字段就可以：

\# 项目名称，将作为于所生成的程序文档首页标题
PROJECT_NAME       = “Test“
\# 文档版本号，可对应于项目版本号，譬如 svn 、 cvs 所生成的项目版本号
PROJECT_NUMBER     = "1.0.0”
\# 程序文档输出目录
OUTPUT_DIRECTORY   = doc/
\# 程序文档语言环境
OUTPUT_LANGUAGE   = Chinese
\# 如果是制作 C 程序文档，该选项必须设为 YES ，否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C  = YES
\# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT   = YES
\# 在 C++ 程序文档中，该值可以设置为 NO ，而在 C 程序文档中，由于 C 语言没有所谓的域 / 名字空间这样的概念，所以此处设置为 YES
HIDE_SCOPE_NAMES    = YES
\# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息
QUIET  = YES
\# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS     = *.h
\# 递归遍历当前目录的子目录，寻找被文档化的程序源文件
RECURSIVE        = YES
\# 示例程序目录
EXAMPLE_PATH      = example/
\# 示例程序的头文档 (.h 文件 ) 与实现文档 (.c 文件 ) 都作为程序文档化对象
EXAMPLE_PATTERNS    = *.c  *.h
\# 递归遍历示例程序目录的子目录，寻找被文档化的程序源文件
EXAMPLE_RECURSIVE   = YES
\# 允许程序文档中显示本文档化的函数相互调用关系 
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION  = YES
REFERENCES_LINK_SOURCE = YES
\# 不生成 latex 格式的程序文档
GENERATE_LATEX     = NO
\# 在程序文档中允许以图例形式显示函数调用关系，前提是你已经安装了 graphviz 软件包
HAVE_DOT        = YES
CALL_GRAPH      = YES
CALLER_GRAPH    = YES
\# 让 doxygen 从配置文件所在的文件夹开始，递归地搜索所有的子目录及源文件
**RECURSIVE = YES**  
\# 在最后生成的文档中，把所有的源代码包含在其中
**SOURCE BROWSER = YES**
$ 这会在 HTML 文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系
**GENERATE TREEVIEW** **＝** **ALL**

2.2. 执行命令