Doxygen可以为C++, C, Java, IDL (Corba and Microsoft flavors) PHP和C#生成文档
大致用途有三:
1. 可以生成一个在线html文档或者一个离线的LATEX格式文档也支持RTF(MS-Word) PostScript, hyperlinked PDF, compressed HTML, 和Unix man pages多种格式生成。文档直接由源码生成,这使得保持文档和代码一致性更加轻松。
2. 可以配置doxygen从无文档的源码中提取代码结构。这就便于在大型源码中迅速上路。也可以将这些不同元素间的关系使用图形表达出来,包括依赖图,继承图和collaboration图,这些都是自动生成的。
3. 甚至可以使用它来生成平常的文档,例如手册
标记以“\”开头,或是一个“@”(使用JavaDoc风格),后面是命令名和一或多个参数。
这些标记都是写在注释块中的,详见随邮件的例子(_common\obj.h)。
说明类型:
分为摘要说明和详细说明
\brief 后紧跟摘要说明,也可以直接使用“//!”开始注释。
详细说明:在摘要说明后,间隔一行书写,见实例。
基本结构的说明标记:
\file [file name] 写文件的说明, 后跟此文件的文件名;另起一行书写此文件的说明文字。
\class [class name] 写类的说明,后跟类名;另起一行书写类的说明文字。
用于函数内部的说明标记:
这些标记会在函数的详细说明中使用不同的字体和格式,突出显示。
\param [param name] 写函数参数的说明,后跟参数名;紧跟参数的说明文字。
\return 写函数返回值得说明,后紧跟返回值得说明。
\warning 警告,后紧跟警告的内容。
\remarks 评论,后紧跟评论的内容。
可单独生成主题的说明标记:
\todo 被此标记说明的代码会在Todo列表中出现。
\bug 被此标记说明的代码会在Bug列表中出现。
\test 被此标记说明的代码会在Test列表中出现。
\deprecated 被此标记说明的代码会在deprecated列表中出现。
\defgroup [group name] [brief] 定义一个代码块,可对代码块写说明;注意group name必须是唯一的;
另起一行写详细说明
\{ 代码块开始
\} 代码块技术
格式化说明标记:
- 主题
-# 子标题1\n
说明
-# 子标题2\n
说明
生成文档中可显示为编号的列表
注意:在注释中,可完全使用html格式化标记。
@author 作者
@brief 摘要
@version 版本号
@date 日期
@file 文件名,可以默认为空,DoxyGen会自己加
@class 类名
@param 函数参数
@return 函数返回值描述
@exception 函数抛异常描述
@warning 函数使用中需要注意的地方
@remarks 备注
@see see also字段
@note brief下空一行后的内容表示详细描述,但也可以不空行用note表示
@par 开始一个段落,段落名称描述由你自己指定,比如可以写一段示例代码
@code 引用代码段
@endcode 引用代码段结束
@pre 函数前置条件,比如对输入参数的要求
@post 函数后置条件,比如对系统状态的影响或返回参数的结果预期
不太常用的标记:
@defgroup 模块名
@name 分组名
@{ 模块开始
@} 模块结束
@deprecated 今后可能将被废弃或已经有替代品的函数
@since 从哪个版本后开始有这个函数的
@todo 被标记的代码会在ToDo列表中出现
@bug 被标记的代码会在Bug列表中出现
@test 被标记的代码会在Test列表中出现
- 一级项目符号
-# 二级项目符号