Doxygen注释格式
Doxygen简介
规范编程注释习惯,提高自己的软实力。Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写,才能让Doxygen识别和转化。
目前Doxygen可处理的程序语言包含C/C++、Java、Objective-C、IDL等,可产生出来的文档格式有HTML、XML、LaTeX、RTF等,此外还可衍生出不少其它格式,如HTML可以打包成CHM格式,而LaTeX可以通过一些工具产生出PS或是PDF文档等。
另外,也可以安装一些辅助工具来生成更加漂亮的文档。如可以使用graphviz中的dot工具来渲染出效果更好的图表,因此,如果需要在注释中加入图表可以下载并安装GraphViz;
Windows平台下还可以安装 Windows Help Workshop来生成 CHM 格式的文档等等。
Doxygen语法
注释格式
块注释建议统一使用
/** |
行注释建议统一使用
///< … |
注释命令
@warning {warning message } 一些需要注意的事情 |
Doxygen示例
项目注释
项目注释块用于对项目进行描述,每个项目只出现一次,一般可以放在main.c主函数文件头部。对于其它类型的项目,置于定义项目入口函数的文件中。对于无入口函数的项目,比如静态库项目,置于较关键且不会被外部项目引用的文件中。
项目注释块以/** @mainpage
开头,以*/
结束。包含项目描述、及功能描述、用法描述、注意事项4个描述章节。
项目描述章节描述项目名称、作者、代码库目录、项目详细描述4项内容,建议采用HTML的表格语法进行对齐描述。
功能描述章节列举该项目的主要功能。
用法描述章节列举该项目的主要使用方法,主要针对动态库、静态库等会被其它项目使用的项目。对于其它类型的项目,该章节可省略。
注意事项章节描述该项目的注意事项、依赖项目等相关信息。
要善于使用表格及一些标号语句
/**@mainpage 春节12响固件程序 |
文件注释
文件注释块对源代码文件进行注释,包括头文件(.h)、C++文件(.cpp)或C文件(*.c)。文件注释块置于对应文件的开头,至少包括文件名(@file)、文件简要说明(@brief)、作者(@author)、创建日期(@date)和版本号(@version)5个标记。
/**@file main.c |
函数注释
该注释块对函数进行描述,位于对应函数的定义上方。
函数注释块包含以下内容:
- 简要说明标记(@brief),内容为方法 / 函数的简要说明。
- 详细描述,详细描述与@brief标记之间空一行””或者使用@details。
- 若干个参数描述标记(@param),数量与该方法的输入参数个数相同。格式为:“@param 参数名称 参数说明”。
- 返回值标记(@return),描述该方法的返回值,格式为:“@return 返回值类型 返回值描述”。若返回值为void类型,则省略该标记。
- 返回值说明(@retval),对具体返回值进行描述说明。
- 特殊标记
-
:生成一个黑心圆.-#
:指定按顺序标记。::
:指定连接函数功能。(注:空格和“:”有连接功能,但建议还是使用”::”。只对函数有用。)
/**@brief 注册函数 |
枚举、结构体
/**@enum msg_types |
模块注释
模块注释用于将一系列相关功能的函数、枚举、结构等归入一个模块并进行描述。模块注释块包括模块起始注释块及模块结束注释块两个部分。
模块起始注释块包含模块名称标记(@defgroup)、模块简介标记(@brief)、模块详细描述及模块起始标记(@{)4个部份。
模块结束注释用于结束一模块描述定义,格式为/** @} */。与模块起始注释块成对出现。包含在模块起始注释块与结束注释块之间的所有内容将归入该模块。
若需要将其它文件中定义的内容归入一个已定义的模块,可使用简略的模块起始注释块与结束注释块括起需要归入该模块的内容。简略的模块起始注释块仅包含相同的模块名称标记(@defgroup)。
/**@defgroup bsp_me3616 Bsp me3616 driver module. |
分组注释
/**@name 协议栈用全局参数 |
Doxygen使用
Doxygen产生文档可以分为三个步骤,一是在程序代码中加上符合Doxygen所定义注释格式;二是使用Doxywizard进行配置;三是使用Doxygen来产生注释文档。现在我们假定电脑中已经安装了Doxygen并且代码中的注释已经符合Doxygen规范,下面我们来通过设置配置来生成注释文档。
填写Doxygen的工作目录、项目名称、源文件目录、生成文档的存放目录,同时递归搜索源文件目录的选项也要勾选。其中,Doxygen的工作目录是指用来存放配置文件的目录。
选择Wizard标签下的Output项,设置输出格式
选择Expert标签下的Project项。其中,编码格式,UTF-8是首选。如果需要显示中文则选择GB2313。OPTIMIZE_OUTPUT_FOR_C 这个选项选择后,生成文档的一些描述性名称会发生变化,主要是符合C习惯。如果是纯C代码,建议选择。SUBGROUPING这个选项选择后,输出将会按类型分组。
选择Expert标签下的Build项。这个页面是生成帮助信息中比较关键的配置页面 | 选项 | 解释 | |------------------|-------------------------------------------------------------------| | EXTRACT_ALL | 输出所有的函数,但是private和static函数不属于其管制 | | EXTRACT_PRIVATE | 输出private函数 | | EXTRACT_STATIC | 输出static函数。同时还有几个EXTRACT,相应查看文档即可 | |HIDE_UNDOC_MEMBERS|那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然,如果EXTRACT_ALL被启用,那么这个标志其实是被忽略的 | | INTERNAL_DOCS | 是否输出注解中的@internal部分。如果没有被启动,那么注解中所有的@internal部分都将在目标帮助中不可见 | | CASE_SENSE_NAMES | 是否关注大小写名称,注意,如果开启了,那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说,建议永远不要开启 | | HIDE_SCOPE_NAMES | 域隐藏,建议永远不要开启 | |SHOW_INCLUDE_FILES| 是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列表 | | INLINE_INFO | 如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明 | | SORT_MEMBER_DOCS | 如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显示 | |GENERATE_TODOLIST |是否生成TODOLIST页面,如果开启,那么包含在@todo注解中的内容将会单独生成并显示在一个页面中,其他的GENERATE选项同 | | SHOW_USED_FILES | 是否在函数或类等的帮助中,最下面显示函数或类的来源文件 | | SHOW_FILES | 是否显示文件列表页面,如果开启,那么帮助中会存在一个一个文件列表索引页面 |
选择Expert标签下的Input项。其中输入的源文件的编码,要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
选择Expert标签下的HTML项。为了解决DoxyGen生成的文件的左边树目录的中文变成了乱码,CHM_INDEX_ENCODING中输入GB2312即可。GENERATE_CHI 表示索引文件是否单独输出,建议关闭。否则每次生成两个文件,比较麻烦。TOC_EXPAND 表示是否在索引中列举成员名称以及分组(譬如函数,枚举)名称
选择 Run 标签。点Run doxygen按钮,Doxygen 就会从源代码中抓取符合规范的注释生成定制的格式的文档。