10分钟速学Doxygen

合集下载

doxygen 函数代码单行注释

在软件开发中，注释是一种非常重要的编程实践，它可以帮助开发者更好地理解代码、提高代码可读性和可维护性。

而在注释中，函数代码的单行注释是一种常见的方式，它可以在一行内就给出对函数的解释和说明。

让我们来看一下什么是Doxygen。

Doxygen是一个广泛使用的工具，它可以从C++、C、Java等多种程序中提取注释，文档化代码。

这个工具能够以较为规范的方式记录代码注释，并生成代码文档。

在Doxygen中，函数代码的单行注释可以被视为标准的注释格式，从而可以被Doxygen正确地解析和转换为文档。

在实际使用Doxygen进行代码注释时，我们需要注意一些关键点。

首先是注释的格式。

对于函数的单行注释，我们通常会在函数定义的上方，使用连续两个斜杠“//”来注释。

接着是对函数的简要说明，包括函数的功能、参数和返回值等。

在Doxygen中，我们可以使用一些特定的标签来标记函数的参数和返回值，例如@param和@return等。

在撰写函数代码单行注释时，我们应该尽量做到深度和广度兼具。

深度上，我们应该从简单的功能和语法说明开始，逐步深入到函数的应用场景、注意事项、使用示例等方面。

而在广度上，我们应该考虑到不同读者的需求，包括初学者、中级开发者和专业开发者等，从而使得注释能够满足不同层次的读者对函数的理解和运用。

从个人角度来看，函数代码的单行注释是一种非常有效的注释方式，它能够在短时间内给出对函数功能和使用方法的简明说明。

但需要注意的是，单行注释可能有字数限制，无法提供过多细节，这就需要在其他地方进行补充说明。

单行注释也容易被滥用，因此在撰写过程中，我们需要注意控制注释的长度和内容，避免出现冗长、无用的注释。

总结而言，Doxygen的函数代码单行注释是非常有价值的，它能够帮助我们更好地理解和使用函数。

在注释时，我们需要遵循规范的格式和标签，做到深度和广度兼具，以满足不同读者的需求。

我希望未来在撰写代码注释时，能够更加注意注释的质量和适用性，让注释真正成为代码文档中的宝贵财富。

Doxygen工具介绍

@collaboration ClassA-<<uses>>->ComponentA::InterfaceA ClassA-<<uses>>->::InterfaceA @endcollaboration
扩展图形（3 扩展图形（3）：类图
@collaboration
ClassA-<<contain>>->[_member_b]ClassB ClassC-<<contain>>->ClassD
Page组织章节组织代码注释
group
1、Page组织 Page组织
mainpage [{title}] page <name> {title} subpage & ref
2、章节组织
section <section_name> (section title) subsection subsubsection ref
扩展图形（1 扩展图形（1）：流程图
@collaboration AAA-<Func1>->BBB AAA-<Func2>->CCC CCC-<Func3>->DDD DDD-<Func4>->EEE DDD-<Func5>->FFF @endcollaboration
扩展图形（2）：IDL 扩展图形（2）：IDL
@endcollaboration
特有图形(原理) 特有图形(原理)
其成立的前提是doxygen支持cmd.endcmdoxygen
Perl
EXE
特有图形(效果)

doxygen

\extends \f$ \f[ \f] \f{ \f} \file \fn \headerfile \hideinitializer \htmlinclude \htmlonly \if \ifnot \image \implements \include \includelineno \ingroup \internal \invariant \interface \latexonly
结果为： A list of events: mouse events mouse move event mouse click event More info about the click event. mouse double click event keyboard events key down event key up event More text here.
@param
@return
@retval
描述返回值类型 eg: @retval NULL 空字符串。 @retval !NULL 非空字符串。
注解注意
@note @attention
@warning
@enum
警告信息
引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg： @enum CTest::MyEnum
\skip \skipline \struct \subpage \subsection \subsubsection \test \throw \throws \todo \tparam \typedef \union \until \var \verbatim \verbinclude \version \warning \weakgroup \xmlonly \xrefitem \$ \@

doxygen介绍

Doxygen1 简介Doxygen是一种开源跨平台的，以类似Java Doc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。

注释的语法与Qt-Doc、KDoc和JavaDoc 兼容。

Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。

2 使用步骤由于只是工具的使用，这里不介绍它的原理，直接从使用步骤开始。

Doxygen的使用步骤非常简单。

主要可以分为：1）第一次使用需要安装doxygen的程序2）生成doxygen配置文件3）编码时，按照某种格式编写注释4）生成对应文档doxygen的安装非常简单，linux下可以直接下载安装包运行即可，下载源代码编译安装也是比较通用的编译安装命令。

Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件：doxygen -g config.ini可以根据项目的具体需求修改配置文件中对应的项，具体的修改过程在下面介绍。

修改过的配置文件可以作为以后项目的模板。

让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。

具体如何写doxygen认识的注释等哈详细介绍。

当代码编完了，注释也按照格式写好了，，运行下面的命令，相应的文档就会产生在指定的目录中(和配置文件的同一目录下的doc文件夹中，都成文件夹中又有3各文件夹(html(也是构成网页文档的主要语言),latex（一种基于TeX的排版系统）,rtf（以纯文本描述内容）))。

doxygen config.ini需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。

3 C++中具体用法文件的注释：/*! \file license.h\brief license处理函数API头文件.详细描述……*/函数的注释：/*! \fn int GenDevInfo(u8 *sOutFileName, u8 *sUpKeyFileName, u8 *sDevInfoFileName, u32 uLastLicId)\brief 获取设备lic请求信息.\param sOutFileName 生成的请求文件存放路径及名字.\param sUpKeyFileName key文件路径.\param sDevInfoFileName 设备编号dev_no存放路径.\param uLastLicId 上一次导入的licID编号.\retval 0 成功\retval 非0 失败*/类的注释：//! A test class./*!A more elaborate class description.*/class Test{public:/** An enum type.* The documentation block cannot be put after the enum!*/enum EnumType{int EVal1, /**< enum value 1 */int EVal2 /**< enum value 2 */};void member(); //!< a member function.protected:int value; /*!< an integer value */}//! class variable./*! Details. */s1,//! class variable./*! Details. */s2;结构体的注释：//! A tt struct./*!A more elaborate class description.*/typedef struct _gwchklic_encinfo{u32 dwBeginTime; /*!< an u32 value */}//! struct variable./*! Details. */GWCHKLIC_ENCINFO,//! struct pointer./*! Details. */*PGWCHKLIC_ENCINFO;宏的注释：/*! \def FUNCMAP\brief A macro that rrrrrrrrrrrrrrr.Details.*/#define FUNCMAP 0全局和静态变量：//! variable./*! Details. */static int test = 0;//! variable./*! Details. */int test1 = 0;4 文档的生成前的配置修改config.ini中选项（主要几个选项）PROJECT_NAME = lonsin ：首页显示名字为lonsinOUTPUT_LANGUAGE = Chinese或English ：输出中文或英文FULL_PATH_NAMES = NO ：是否要显示全路径的文件名SHOW_INCLUDE_FILES = NO ：是否显示包含的头文件INPUT = include/license.h ：可以是文件也可以是文件夹INPUT_ENCODING = GB18030 ：输入的中文字体（UTF-8 GB18030）FILE_PATTERNS = *.cpp ：输入文件的样式(*.c *.h ……)EXCLUDE_SYMLINKS = YES ：显示时排除连接或宏EXTRACT_STATIC=NO：是否包含静态变量EXTRACT_PRIVATE=NO：是否显示私有成员。

doxygen文档注释简介

/*!
Details.
*/
int (*handler)(int a,int b);
};
如果配置文件中JAVADOC_AUTOBRIEF 设置成 YES，可以使用JavaDoc风格注释
/**
* A test class. A more elaborate class description.
/*! Details. */
*enumPtr,//! Enum variable.
/*! Details. */
enumVar; //! A constructor.
/*!
A more elaborate description of the constructor.
/** 简要说明.
* 详细说明.
*/
多行C++风格注释：
/// 简要说明.
/// 详细说明.
3、可以采用如下注释：
/// 简要说明.
/** 详细说明. */
或者
//! 简要说明.
//! 详细（上面的空行是需要的）
//! 说明.
上例中间空行用来分隔简要说明和详细说明的。请注意下面格式的注释是不合法的，doxygen只允许一条详细说明对应一条简要说明：
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test() testMeToo()
/**
* A constructor.
* A more elaborate description of the constructor.

doxygen参考

Doxygen 的处理流程
图 1 是 Doxygen 网站上给出的 Doxygen 处理工具以及它们之间的信息流。
从图中可以看出，Doxygen 可执行程序位于正中，所有的流程都围绕着它进行。左侧图标表示 Doxygen 的输入可以是源文件，或者是定制的头文件、图像、注解等。Doxygen 图标上部是配置文件，由 Doxywizard 处理，下部是 Tag 文件，由 Doxytag 处理。后面是 Doxygen 输出文件的类型，依次是 XML、Latex、Man pages、 RTF 和 HTML，可处理类型图标之后是进行进一步转换所需的工具。
分组
Doxygen 有两种分组机制。第一种是全局地为每一个组创建一个网页，此时分组被称为"module"；第二种是用于复合实体中的成员列表，此时分组被称为 "member group"。Module 是一种把内容在单个网页上分组的方法。分组可以包括 files，namespace，classes，functions，variables，enums，typedefs 和 defines，也可以包含其它分组。复合实体（compound entities）如类、文件、
忽略<config-file>将会生成一个名为 Doxyfile 的缺省文件，如果 <config-file>已经存在，会被 Doxygen 改名为<config-file>.bak。
实际上，我们根本就不需要用一般的编辑器来编辑配置文件，Doxygen 提供了一个辅助工具 Doxywizard。Doxywizard 是 Doxygen 的 GUI 前台，用户可以能过它来读写配置文件，省却了手工配置的麻烦。基本上，在 Doxywizard 中可以完成 Doxygen 的绝大多数工作，而且 Doxygen 也可以在由 Doxywizard 启动，这样就使得整个过程比较连贯。

Doxygen配置(翻译)-ASP教程,ASP应用

使用doxygen文档开发工具时需要进行的配置：可执行文件doxygen 是原代码分析和生成文档的主要工具. 请看doxygen usage 章节来获取更详细的使用帮助.doxytag可执行文件---仅仅是用来实现帮助程序员生成不需要看原代码就能了解工程部署信息的doxygen文档的参考文档( 例如：那些使用doxygen生成的文档).请看doxytag usage 章节来获得更多的使用帮助.doxywizard 可执行文件很容易就能使用,它是用来为doxygen工具提供配置信息的一个图形化工具.下面的图显示了开发工具之间的相互关系信息:http://www.stack.nl/~dimitri/doxygen/infoflow.gif图：doxygen information flowstep 1: 创建一个配置文件doxygen使用一个配置文件来确定它所有的设置. 每个工程都应该有它自己的配置文件.一个工程可以只有一个原文件, 也可以是工程中所有原文件的递归扫描得到的原文件的树状视图。

为了简化doxygen生成配置文件的工作, doxygen 可以为你提供一个模板化的配置文件.1. 为了创建一个模板化的配置文件，只需要调用doxygen并从命令行中敲入-g:doxygen -g <config-file>其中<config-file>是某个模板化的配置文件的文件名. 如果你省略了文件名, doxygen会为你生成一个默认的doxyfile的配置文件. 如果<config-file>是一个已经存在的文件名, doxygen 在生成配置模板之前，将会生成一个<config-file>. bak 备份文件。

2. 如果你使用- (例如：减号) 作为文件名doxygen将会把你从键盘输入的文字当作配置文件名。

配置文件有着和makefile相似的格式.主要是：包含了很多的“标志”分配符格式(tags):例如：tagname = value ortagname = value1 value2 ...在生成文档模板时，你可以使用默认（即：保留大多数的tags）详细信息请看configuration 这一章节来获取更多的信息.如果你不想使用文本编辑工具来编写配置文件,你应该看看doxywizard 章节的描述, 它是一个可以用来创建/读/写doxygen 配置文档的图形化工具，同时它也可以在路径中进行全路径配置来使doxygen正常工作。

doxygen的简要用法

Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage，Doxygen软件可以从这里下载，软件本身用法非常简单。

这里不做介绍，下面主要是代码中doxygen 的注释的写法的介绍。

1. 模块定义（单独显示一页）/** @defgroup 模块名模块的说明文字* @{*/… 定义的内容…/** @} */ // 模块结尾2. 分组定义（在一页内分组显示）/** @name 分组说明文字* @{*/… 定义的内容…/** @} */3. 变量、宏定义、类型定义简要说明/** 简要说明文字 */#define FLOAT float/** @brief 简要说明文字（在前面加 @brief 是标准格式） */#define MIN_UINT 0/** 分行的简要说明 \n* 这是第二行的简要说明*/int b;4. 函数说明/** 简要的函数说明文字* @param [in] param1 参数1说明* @param [out] param2 参数2说明* @return 返回值说明*/int func(int param1, int param2);/** 打开文件 \n* 文件打开成功后，必须使用 ::CloseFile 函数关闭。

* @param[in] file_name 文件名字符串* @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成：* – r 读取* – w 可写* – a 添加* – t 文本模式(不能与 b 联用)* – b 二进制模式(不能与 t 联用)* @return 返回文件编号* – -1 表示打开文件失败* @note 文件打开成功后，必须使用 ::CloseFile 函数关闭* @par 示例:* @code// 用文本只读方式打开文件int f = OpenFile(”d:\\test.txt”, “rt”);* @endcode* @see ::ReadFile ::WriteFile ::CloseFile* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。

C++ doxygen讲解

●变量、宏定义、类型定义。
●枚举类型定义、结构体类型定义类似。
●函数定义。 ●模块定义（单独显示一页
）。 ●分组定义（在一页内分组显示）。
变量、宏定义、类型定义简要说明
变量、宏定义、类型定义注释风格类似。格式： /** 简要说明文字 */ 变量（宏定义或类型定义）
如： /** 简要说明文字 */ #define FLOAT float
pre 指令操作符讲解
pre：指定函数前置条件指令操作符 pre格式如下： @pre 简要说明
例: /** *文件关闭函数 * @param file文件编号。 * @retval 0 表示成功 * @retval -1 表示失败 * @pre file 变量必须使用OpenFile 返回值 */ int CloseFile(int file);
retval指令操作符讲解
retval：指定函数返回值说明指令操作符。(注:更前面的return有点不同.这里是返回值说明) retval格式如下： @retval 返回值简要说明例:
/** *文件关闭函数 * @param file文件编号。 * @retval 0 表示成功 * @retval -1 表示失败 */ int CloseFile(int file);
“\n”作用是回车换行.
注：不文档化局部变量，只文档化全局变量。
枚举类型定义、结构体类型定义
枚举类型定义、结构体类型定义注释风格类似。格式：
/** 简要说明文字 */ typedef 类型结构体名字 { 成员1, /**< 简要说明文字 */ 成员2, /**< 简要说明文字 */ 成员3, /**< 简要说明文字 */ }结构体别名；
see指令操作符讲解

doxygen使用总结

doxygen使⽤总结doxygen[功能]为许多种语⾔编写的程序⽣成⽂档的⼯具。

[举例]*⽣成⼀个模板配置⽂件，模板⽂件中有详细的注释：$doxgen -g test这样，会⽣成⼀个test⽂件,1500多⾏，可以把这个⽂件做为模板编写配置⽂件。

如果之前有test那么会将原来的test备份为test.bak.模板⽂件的部分内容如下：...前⾯的内容省略...DOXYFILE_ENCODING = UTF-8# The PROJECT_NAME tag is a single word (or a sequence of words surrounded# by quotes) that should identify the project.PROJECT_NAME =# The PROJECT_NUMBER tag can be used to enter a project or revision number.# This could be handy for archiving the generated documentation or# if some version control system is used.PROJECT_NUMBER =# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)# base path where the generated documentation will be put.# If a relative path is entered, it will be relative to the location# where doxygen was started. If left blank the current directory will be used.OUTPUT_DIRECTORY =...后⾯的内容省略...*⽣成⼀个模板配置⽂件，模板⽂件中只有简单的注释：$doxygen -s -g test这⾥，我尝试并且⽐较过，如果使⽤⽣成的⽂件只200多⾏，⼏乎没有注释,只有⼏⾏分类的注释，去除了多余的注释。

doxygen讲解

向导(Wizard)对话框----Output相关选项
生成普通模式的HTML 生成文件列表格的HTML
生成chm文件格式的HTML, 因此,就选这个.
附带查找功能,一般不选择. 这项没用到,因此把它选择取消. 这三项不要选择
向导(Wizard)模式

向导(Wizard)对话框----Diagrams相关选项
注：不文档化局部变量，只文档化全局变量。
枚举类型定义、结构体类型定义
枚举类型定义、结构体类型定义注释风格类似。格式：类型：enum ，struct
/** 简要说明文字 */ typedef 类型结构体名字 { 成员1, /**< 简要说明文字 */ 成员2, /**< 简要说明文字 */ 成员3, /**< 简要说明文字 */ }结构体别名；
专家(Expert)模式

专家(Expert)对话框----Dot相关选项
可以选上UML_LOOK、CALL_GRAPH和 CALLER_GRAPH。CALL_GRAPH是本函数调用其它函数的示意图.效果如: 图3.
图3
Doxygen注释风格
Doxygen指令目的为了生成更丰富与可读性更强的文档。所以总结5类常用的注释风格说明。
附带操作
为了方便运行Doxygen工具与管理.为每个模块创建一文件夹(如：“TEST”),在TEST文件夹里再创建src、 doc文件夹。Src文件夹存放源文件，doc文件夹存放 Doxygen输出文件。顺便把doxygenWD.bat和Doxygen 配置文件“Doxyfile” 拷贝到doc文件夹下，如果要生成文档就双击doxygenWD.bat即可。（模块的目录结构 TEST 如下）

[总结]doxygen的使用与CC++注释规范

[总结]doxygen的使⽤与CC++注释规范近期由于项⽬需要，参考⽹上资料整理了⼀下注释规范，详细内容如下：1. doxygen的安装与参数配置1.1. 安装$ sudo apt-get install doxygen以下可以选择安装$sudo apt-get install doxygen-doc doxygen-gui graphviztexpower dot2tex graphviz-doc texpower-examples1.2. ⽣成配置⽂件在 shell 提⽰上，输⼊命令 doxygen -g。

这个命令在当前⽬录中⽣成⼀个可编辑的配置⽂件 Doxyfile。

可以改变这个⽂件名，在这种情况下，应该调⽤ doxygen -g<user-specified file name>1.3. 修改配置参数l <OUTPUT_DIRECTORY>：必须在这⾥提供⼀个⽬录名，例如 /home/user1/documentation，这个⽬录是放置⽣成的⽂档⽂件的位置。

如果提供⼀个不存在的⽬录名，doxygen 会以这个名称创建具有适当⽤户权限的⽬录。

l <INPUT>：这个标记创建⼀个以空格分隔的所有⽬录的列表，这个列表包含需要⽣成⽂档的 C/C++ 源代码⽂件和头⽂件。

例如，请考虑以下代码⽚段：INPUT = /home/user1/project/kernel /home/user1/project/memory在这⾥，doxygen 会从这两个⽬录读取C/C++ 源代码。

如果项⽬只有⼀个源代码根⽬录，其中有多个⼦⽬录，那么只需指定根⽬录并把<RECURSIVE> 标记设置为 Yes。

l <FILE_PATTERNS>：在默认情况下，doxygen会搜索具有典型C/C++ 扩展名的⽂件，⽐如.c、.cc、.cpp、.h和.hpp。

如果<FILE_PATTERNS> 标记没有相关联的值，doxygen就会这样做。

DOXYGEN简明实用教程

DOXYGEN 简明实用教程DOXYGEN 简明实用教程1.所有注释都可以使用III开始（C++风格）。

2•类体前必须加上///描述，否则会产生警告【Compound 类名is not documented】描述中最好不要带有此类的类名，否则会产生两个链接（但指向同一个文件）影响美观。

3.public 和protected 会自动生成，但是private 要在Expert 的Build 选项里勾中EXTRACT_PRIV ATE，static 成员也是如此。

4.函数注释方式III Constructor 【函数描述】III @param [in] pos The position of Camera in world coordinate 【参数描述 1 】III @param [in] lookat The point Camera looks at in world coordinate 【参数描述2】BaseCamera（ const D3DXVECTOR3& pos, constD3DXVECTOR3& lookat ）;5. 变量注释方式D3DXVECTOR3 m_Position; I*!< Camera position point in world coordinate *I 或D3DXVECTOR3 m_Position; III< Camera position point in world coordinate两种方式产生的结果不同。

前者会单独产生一块Member DataDocumentation 注释，后者会在Pubilc/Protected/Private Attributes 变量描述后紧跟注释。

6.@参数和参数相同7.产生描述顺序和注释顺序相同，一般风格为lll 函数描述lll @param 参数描述lll @return 返回值描述lll @retval 返回值 1 返回值 1 描述lll @retval 返回值 2 返回值 2 描述lll @remarks 注意事项Ill @note 注意事项，功能同@remarks,显示字样不同/// @par 自定义图块，后面可跟示例代码之类Ill @code（必须使用@endcode结束）lll 示例代码（无需缩进）lll @endcodelll @see 其他参考项【产生指向参考的链接】函数代码声明8.特殊符号lll - 产生一个黑色圆点9.定义在类体里面的enumlll Camera typesenum CAMERA_TYPECAMERA_FIRST_VIEW,l*!< Camera that looks from thefirst view */CAMERA_MODEL_VIEW,///< Camera that looks from the third view};两种风格相同。

一款常用文档生成工具：Doxygen

一款常用文档生成工具：Doxygen程序员的很多文档，特别是有代码的文档，绝大部分都是由一款文档生成工具【Doxygen】生成。

什么是Doxygen?Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。

通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。

大部分有用的批注都是属于针对函式，类别等等的说明。

所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用你的程序代码的人而言将会减少许多的负担。

不过，反过来说，整理文件的工作对于你来说，就是沉重的负担。

简而言之，Doxgen就是大名鼎鼎的文档生成工具，而且是免费开源的，它使用非常方便，能提取C++，Java，Objective-C，Python，IDL，PHP，C#等语言的注释，从而生成文档。

Doxygen 的使用可分为两大部分。

首先是特定格式的批注撰写，第二便是利用Doxygen的工具来生成文档。

生成文档使用教程1、安装在Linux下可以通过apt install doxygen安装命令行工具，然后用apt install doxygen-gui安装图形界面。

对Linux用户来说，命令行工具可以通过doxygen命令运行，而图形界面可以通过doxywizard命令运行。

Windows 用户的下载地址：/download.html2、基本使用图形工具的基本使用如下图所示，有非常多的配置选项，这里我们只填入必要的配置，其它配置都用默认值。

doxywizard使用步骤doxywizard使用步骤工作目录如下：.├── out└── src└── math.h其中math.h代码如下：/*! \file math.h *//*!用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示\li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角\li 角度制用d结尾，例如：360d表示一圈、90d表示直角\li 输入也可以是数值，例如：输入3.14159大约表示180度\param a 用弧度制或角度制表示都行，字符串必须用'\0'表示结束\param[out] res 是输出参数，用于保存sin运算的结果\return 错误码，0表示成功，其它表示失败\todo 在xxx的情况下存在BUG，预计下一版本修复*/int sin(char *a, double *res);Doxygen生成的HTML会放到out目录下，生成的HTML如下图所示。

《Doxygen中文手册》之索引

《Doxygen中文手册》之索引介绍Doxygen是可用于C++、C、Java、Objective-C、Python、IDL (Corba 和Microsoft flavo rs)以及部分PHP、C#和D语言的文档系统。

它能通过以下三种方式帮助你：1，它能从一系列源文件中生成在线浏览文档（HTML形式）或离线参考手册（LATEX形式）。

还支持RTF（MS-Word），PostScript，带超链接的PDF，压缩的HTML和Unix man页。

文档是直接从源文件中提取出来的，这使得文档与源代码很容易保持同步。

2，通过配置doxygen，你可以从未文档化的源文件中提取出代码结构。

这对于从大的源码包中快速理清头绪是非常有用的。

它还能自动产生出包含关系图、继承图和协作图，使你能直观地看出各种元素间的关系。

3，你甚至可以“滥用“doxygen来创建平常的文档（就像本文档）。

doxygen是在Linux和Mac OS X下开发的，但是它被设计成高可移植的。

这使得它可运行在其它Uni x变种操作系统上。

此外，它还能在windows下运行。

本手册分为三部分，其中每个部分又分为几节。

第一部分是用户手册：∙Installation一节讨论了如何在你的平台上下载、编译和安装doxygen。

∙Getting started一节告诉你如何快速地产生你的第一块文档。

∙Documenting the code 一节示范了代码被文档化的多种方法。

∙Lists 一节展示了如何创建项目列表。

∙Grouping一节展示了如何将各种东西集合在一起以组成一个项目列表。

∙Including formulas一节展示了如何在文档中插入规则。

∙Graphs and diagrams描述了doxygen可生成的图表和图形。

∙Preprocessing一节说明了doxygen是如何处理宏定义的。

∙Automatic link generation一节展示了如何在文档中链接文件、类和成员。

doxygen命令行

doxygen命令⾏⽂档与⽂档系统不做⽂档是⾮常⼀个项⽬，它需要的维护的东西可以分为两个部分：代码与⽂档！除⾮⼀个⾮常⼩的项⽬，否则的话不做⽂档是⾮常危险的事。

做项⽬是为了什么？这是⼀个关键的问题，当然做项⽬不是为了代码，也不是为了⽂档，做项⽬是为了项⽬可以取得的效果。

这句话讲得有⼀点冒险，我担⼼有许多⼈想给我⼀个⽯⼦，可是真理往往就是如此直⽩⽆奇。

微软做Windows，它不是为了做Windows，⽽为了赚钱或者可能有⼀部分⼈做出⼀个操作系统，它会帮助⼈们完成许多事。

试想⼀下，如果现在的⼈⼯智能已经相当先进了，⼈机交互可以像⼈与⼈交互⼀样，Windows还存在吗？所以总结⼀句：项⽬的⽬的是达到项⽬预期的⽬标。

上⾯的说法好像与本⽂的标题没有关系了，其实不然，要达到项⽬的⽬标，我们就必须通过某种⼿段达到。

代码和⽂档是⼿段！代码与⽂档哪个更重要这个问题本⾝就是荒诞的，我想问你左⼿和右⼿哪个更重要？要是你是左撇⼦，可能会说左⼿更重要；可要是你是⼀个右撇⼦呢？代码可能离我们⽬标更直接⼀些，因为程序最终都以某种形式的代码来体现的，但是没有⽂档是没有办法完成代码的。

本⽂不说代码，本⽂说的⽂档。

⽂档⼤致分为两种：设计⽂档和解释⽂档。

前⾯那个词⼤家经常听到，后⾯这个词是我⾃⼰发明的。

设计⽂档指导代码的写作，⽽解释⽂档解释代码为什么是如此；前者⽤于写代码，后者⽤于读代码！写代码的原因⼤家都明⽩，读代码原因可能还有疑惑，读是为了更好地写，也是为了更好的设计。

需要维护⼤量⽂档的时候，⽂档⼯作就变成⼀个系统⼯作，此时它需要的不仅仅是⼈的热情，同时它更需要⼀个机制来作为保证，如此产⽣了⽂件系统──⽤于维护⼤量⽂档的机制或⽅法。

设计⽂档与解释⽂档存在区别，设计⽂档是由⽆到有的过程，解释⽂档则与⼀个解释对象关联。

前者关⼼的核⼼问题是如何设计⼀个可⽤的作品，后者关⼼的是解释哪个对象，所以任务是不同的两个任务，相应的⽂档系统就不⼀样。

doxygen常用注释语法

2.常用注释语法注释写在对应的函数或变量前面。

简要注释和详细注释：/*** @brief Brief Description.** Detailed Description*/简要注释遇到一个空行或新的命令会结束，后面的就表示是详细注释。

JavaDoc风格下，自动会把第一个句号前的文本作为简要注释，后面的为详细注释。

你也可以用空行把简要注释和详细注释分开。

注意要设置JAVADOC_AUTOBRIEF设为YES。

为了注释一个类中的member，首先要对该类作注释。

同样的问题上升到namespace。

要注释一个全局的function，typedef，enum或preprocessor定义，你需要首先定义（只能用@file，因为文件不再任何东西里面，就只能用特殊命令实现了，而不像类、函数等，既可以在上方放注释，也可以用@class、@fn进行注释）包含它的文件。

（1）文件头注释/** @file [file‐name]*@brief brief description* @author <list of authors>* [@author <authors description>]* @date <date>* @version <version number>* @note* detailed description*/一般@file后我们空着，Doxygen会默认为是@file所在文件的文件名。

[]表示可选，{}表示重复0到N次，<>表示必须参数。

@author 表示作者，@data表示日期，@version表示版本号。

（2）类注释/*** @class <class‐name> [header‐file] [header‐name]* @brief brief description* @author <list of authors>* @note* detailed description*/header‐file是类声明所在的头文件名字，header‐name是要显示的链接文字，一般为头文件的真实路径。

Doxygen注释常用标记

Doxygen注释常用标记Doxygen的常用注释标记，通过这些标记，可生成规范化的代码文档；也可以帮助我们管理代码。

这些标记都是写在注释块中的，详见随邮件的例子(_common/obj.h)。

说明类型：分为摘要说明和详细说明/brief 后紧跟摘要说明，也可以直接使用“//!”开始注释。

详细说明：在摘要说明后，间隔一行书写，见实例。

基本结构的说明标记：/file [file name] 写文件的说明，后跟此文件的文件名；另起一行书写此文件的说明文字。

/class [class name] 写类的说明，后跟类名；另起一行书写类的说明文字。

用于函数内部的说明标记：这些标记会在函数的详细说明中使用不同的字体和格式，突出显示。

/param [param name] 写函数参数的说明，后跟参数名；紧跟参数的说明文字。

/return 写函数返回值得说明，后紧跟返回值得说明。

/warning 警告，后紧跟警告的内容。

/remarks 评论，后紧跟评论的内容。

可单独生成主题的说明标记：/todo 被此标记说明的代码会在T odo列表中出现。

/bug 被此标记说明的代码会在Bug列表中出现。

/test 被此标记说明的代码会在Test列表中出现。

/deprecated 被此标记说明的代码会在deprecated列表中出现。

/defgroup [group name] [brief] 定义一个代码块，可对代码块写说明;注意group name必须是唯一的；另起一行写详细说明/{ 代码块开始/} 代码块技术格式化说明标记：- 主题-# 子标题1/n说明-# 子标题2/n说明生成文档中可显示为编号的列表注意：在注释中，可完全使用html格式化标记。

以上是常用的标记的简要说明；还是建议大家看doxygen的文档来熟悉一下。