基于Doxygen的注释风格

维护一份注释就可以维护一份文档,我们需要Doxygen!我们见过opencv、pcl等很多开源库的代码和网站,他们的代码文档都是doxygen生成的,就像title图中那样。

这篇博客简单介绍doxygen使用的注意事项,后面C++风格注释部分摘抄了这篇博客中的内容。欢迎访问原博客。

使用doxygen

下载doxygen,我们可以使用命令行的doxygen,也可以使用带gui的doxygen,选择源码目录和要生成文档的目录,勾选递归,doxygen就可以自动扫描文件生成html和latex等文档。

需要注意linux下的doxygen采用命令行、编辑配置文件方式进行配置,刚入手需要查阅文档

另外,还需要注意,中文乱码问题,Input->Encoding 需要修改成 GB2312

C++注释风格

C++的注释风格 主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’

文件注释

/**

*@file 文件名

*@brief 概述

*

*详细概述

*

*@author 作者,包含email等

*@version 版本号(maj.min,主版本.分版本格式)

*@date 日期

*/

 

命名空间的注释

///@brief 简单概述

///

///详细概述

 

类定义注释

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

 

///@brief 简要概述

///

///详细说明

///

///使用指南设计函数调用可以@ref 函数名 用于引用其他的说明

///

///其他说明,重写父类函数加以特殊实现

///

///@invariant 类不变项,例如哪些值不会超多少多少

///

class xxx

{…

数据声明注释

行尾说明

Type varName;///< 说明

 

多行说明

///说明

///

///

Type varName;

函数注释规范

///@brief 简单概述

///

///详细说明

///@param[in|out] 参数名,in,out表示输入还是输出

///@pre 前者条件

///@return 说明

///@retval 返回值 说明, 这个是可选的

///@post 说明函数完成后的世界状态

代码标记数值规范

///@todo 将要做的代码

///@bug 表示此处的bug描述

 

枚举变量的注释示例 

///    颜色的枚举定义  

///   

///    该枚举定义了系统中需要用到的颜色\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 <name> [<header-file>] [<header-name>]

eg:

@class CTest “inc/class.h”

@exception

可能 产生的异常描述

eg:

@exception 本函数 执行可能会产生超出范围的异常

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

2  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 执行命令

doxygen yourconfigname

这一条命令就可以在指定的目录下生成 html 目录(根据配置决定,也可以生成帮助文档等)

发表评论