doxygen的简要用法.doc

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 函数关闭。* paramin file_name 文件名字符串* paramin 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 由于特殊的原因，这个函数可能会在将来的版本中取消。*/int OpenFile(const char* file_name, const char* file_mode);5. 枚举类型定义/* 枚举常量 */typedef enum TDayOfWeekSUN = 0, /* 星期天（注意，要以 “” 小于号开头） */MON = 1, /* 星期一 */ TUE = 2, /* 星期二 */ WED = 3, /* 星期三 */ THU = 4, /* 星期四 */ FRI = 5, /* 星期五 */ SAT = 6 /* 星期六 */ /* 定义类型 TEnumDayOfWeek */TEnumDayOfWeek;6. 项目符号标记/* A list of events:* mouse events* -# mouse move event* -# mouse click eventn* More info about the click event.* -# mouse double click event* keyboard events* -# key down event* -# key up event* More text here.*/结果为：A list of events: mouse events 1. mouse move event 2. mouse click eventMore info about the click event. 3. mouse double click event keyboard events 1. key down event 2. key up event More text here.代码示范：/* defgroup EXAMPLES 自动注释文档范例* author minidxer* version 1.0* date 2007-2008* */* name 文件名常量* */* 日志文件名 */#define LOG_FILENAME “c:logdebug.log”/* 数据文件名 */#define DATA_FILENAME “c:datadetail.dat”/* 存档文件名 */#define BAK_FILENAME “c:databackup.dat”/* */ / 文件名常量/* name 系统状态常量* */ /* 正常状态 */#define SYS_NORMAL 0/* 故障状态 */#define SYS_FAULT 1/* 警告状态 */#define SYS_WARNNING 2/* */ / 系统状态常量 /* 枚举常量 */typedef enum TDayOfWeekSUN = 0, /* 星期天 */MON = 1, /* 星期一 */TUE = 2, /* 星期二 */WED = 3, /* 星期三 */THU = 4, /* 星期四 */FRI = 5, /* 星期五 */SAT = 6 /* 星期六 */* 定义类型 TEnumDayOfWeek */TEnumDayOfWeek;/* 定义类型 PEnumDayOfWeek */typedef TEnumDayOfWeek* PEnumDayOfWeek;/* 定义枚举变量 enum1 */TEnumDayOfWeek enum1;/* 定义枚举指针变量 enum2 */PEnumDayOfWeek p_enum2;/* defgroup FileUtils 文件操作函数* */ /* 打开文件 n* 文件打开成功后，必须使用 :CloseFile 函数关闭。* paramin file_name 文件名字符串* paramin file_mode 文件打开模式字符串，可以由以下几个模块组合而成：* r 读取* w 可写* a 添加* t 文本模式(不能与 b 联用)* b 二进制模式(不能与 t 联用)* return 返回文件编号* -1 表示打开文件失败 * note 文件打开成功后，必须使用 :CloseFile 函数关闭* par 示例:* code/ 用文本只读方式打开文件int f = OpenFile(”c:test.txt”, “rt”);* endcode * see :ReadFile :WriteFile :CloseFile* deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。*/int OpenFile(const char* file_name, const char* file_mode);/* 读取文件* paramin file 文件编号，参见：:OpenFile* paramout buffer 用于存放读取的文件内容* paramin len 需要读取的文件长度* return 返回读取文件的长度* -1 表示读取文件失败 * pre e file 变量必须使用 :OpenFile 返回值* pre e buffer 不能为 NULL* see :OpenFile :WriteFile :CloseFile*/int ReadFile(int file, char* buffer, int len);/* 写入文件* paramin file 文件编号，参见：:OpenFile* paramin buffer 用于存放将要写入的文件内容* paramin len 需要写入的文件长度* return 返回写入的长度* -1 表示写入文件失败 * pre e file 变量必须使用 :OpenFile 返回值* see :OpenFile :ReadFile :CloseFile*/int WriteFile(int file, const char* buffer, int len);/* 关闭文件* param file 文件编号，参见：:OpenFile* retval 0 为成功* retval -1 表示失败 * see :OpenFile :WriteFile :ReadFile* deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。*/int CloseFile(int file);/* */ / 文件操作函数 /* */ / 自动注释文档范例Doxygen简单经验谈。 Doxygen，大名鼎鼎的文档生成工具，被Boost、OpenCasCade等诸多项目作为文档生成的不二人选。人说，才华横溢往往是高深莫测，这句话放在 Doxygen这里显然是不适用的。十八般武艺样样精通的Doxygen，却十分的简单易用，从头到尾看一下它随机的文档，想不会用都难。嫌看英文麻烦的，这里有一篇中文的入门介绍。简单的说，如果你准备在项目中采用Doxygen作为文档生成的工具，首先，你需要了解，Doxygen需要什么样的代码结构才能够生产文档。 Doxygen基本上对光秃秃的代码不感兴趣，你需要在所有的类、函数、成员函数、公共变量、名字空间等代码已有表示的结构上方添加上指定格式的注释，Doxygen才能识别出来。此外，你还可以按照指定格式的注释添加附加的信息，用以生成模块的分类，架构图之类的信息。Doxygen支持的注释格式多种多样，强烈建议制定一个统一的标准，否则会给项目中其他的人员或者后来的人员带来很多的困扰。按照指定的格式书写了注释之后，就需要写一个Doxygen的配置文件，依照此配置文件，Doxygen可以生产HTML、Tex、XML等多种格式输出文档。Doxygen的配置文件，有辅助的GUI工具帮助书写，你只需要改几个选项，点几下按钮就信手拈来了。但在此强烈建议，你应该把Doxygen每一个配置值的含义都了解一下，写一些简单的例子实践一下，这样一则你可以清楚的明白你需要的格式该如何配置出来，二则你可以充分了解Doxygen可以做到什么程度，以备不时之需。Doxygen通常是用作生成英文文档的，生成中文文档需要修改输入和输出的码制，这样可以改变解析方式，生成中文文档。但是，你必须意识到，Doxygen在从注释中抽取信息是需要做语法解析的，这些解析都是基于英文的基础，不可能在这个层面上支持中文。比如，一个类的简明信息和详细信息的分隔，是通过英文的句号“.”来识别的，如果你用中文的句号“。”，Doxygen就分辨不出来了。再比如，在某个类的注释中，你写 Created by xxx function，其中xxx是某个方法名，Doxygen会在生成的文档中，自动为该函数添加上链接。当如果你用中文：该类是被xxx方法构造出来的。 Doxygen就无法抽取出该信息并添上链接。你要按如下格式来写：该类是被 xxx 方法构造出来的。用强行的人肉空格帮助Doxygen。所有类似的问题都可以以此类推。我们说，Doxygen无法识别光秃秃的代码信息，这并不意味着代码结构对Doxygen来说不重要。Doxygen可以对各种语言书写的代码进行优化，比如你开启C+代码优化后，Doxygen会解析你写的C+代码，添加更多更具体的信息，并依照之间联系为你添加链接。这也就是说，Doxygen会产生真实的代码结构表示出来的东西，你在写注释的时候也应该按照严谨的代码结构去写。比如，你在某个类A的注释中写道：此类用到了 B 类中的方法。假设B这个类，在名字空间N1内，如果，你的A类同样也是在N1内，这个链接Doxygen会为你自动添加，但是，如果B这个类在名字空间 N2内，Doxygen会无视你的请求。你必须严格的写它的全名 N2:A，Doxygen才会欣然接受这个娃。我在做的项目比较小，因此我利用Doxygen的ToDo-List和Bug列表对项目进行简单的管理。比如，有一个类你有一些后续的工作没有完成，你可以在其注释中加上todo xxx，（这只是其中一种语法，不是唯一的规范.）Doxygen会将其链接添加到一个to do list中，并为该to do list生成一个页面，查看起来颇为方便。同样，Bug标记也是这么用这么看的，举一反三大家都会，我就不多磨叽了。Doxygen中利用到很多第三方的基于编译的信息生成工具，辅助生成更为炫目的文档。比如，你可以在注释中嵌入符合tex标准的公式，Doxygen帮助你把这些显示到你的文档中来；你还可以为你的文档自动生成继承图，组合图，UML格式的图，等品种齐全的图，只要你把Graphviz装上，并打开相关参数即可。更漂亮的是，利用Graphviz的dot方法，你可以将符合其格式的画图指令写在注释中，场景图，架构图，流图，交互图，隔壁校长含泪跳楼图，只要你能用Graphviz画出，Doxygen都能给你用上，图例想改就改想变就变，幸福生活，不过尔尔。而关于Graphviz，g9老大已经推荐过了，再多的好话也就显得苍白。这东西无疑是好东西，方便的一塌糊涂，对于常年和代码打交道对直观之物缺失判断的程序员而言，这无疑是居家旅行杀人必备的水果刀。但要把水果刀玩的和关公大刀似的，是需要不俗功力的，像我这样三脚猫的功夫，就只能关注功能而无法挑战美观了。其他的信息，比如author，date，group，之类的，我都会要求写注释的时候加上，举手之劳，可以方便很多后续可能出现的问题。每一个简单到无需注释的函数，也要加一个空的注释头，以便生成文档的时候，所有的方法都齐备；如果有需要，你可以修改配置文件的设置，把代码也绑定进文档，这样别人只要拿着文档一看，几乎就完全不用在添一份代码放在手上了。把文档与代码绑定在一起，这是用Doxygen之类工具的一个好处，它至少可以产生两个方面的生产力。一方面，它可以帮助你构建结构良好的文档，生成真正可看好看的文档来；另一方面，它可以刺激你更新文档，把文档工具当作项目管理工具用起来。当然，如果文档就在你写的代码上面两行你都懒的看一眼，那么，啥工具也挽救不了了。用这类工具，必须要文档代码配合着写，配合着看，把它提升到和写单元测试一个习惯级别来，看一眼注释，写一段代码，然后测一测，改改过期注释，就像蘸酱卷饼吃黄瓜一样一气呵成，那么，Doxygen就可以今夜做梦也会笑了。使用doxygen为C/C+程序生成中文文档（上）按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。通过这种方式产生文档至少有以下好处： 便于代码和文档保持同步。 可以对文档做版本管理。 很多编程语言都有类似的文档工具，例如：Java有javadoc，Ruby有rdoc。对于C/C+程序，我们可以用Doxygen生成文档。本文通过为一个C+程序“谁养鱼”建立文档，介绍了怎样在Windows平台使用Doxygen。Doxygen比较适合制作API的接口文档，CHM是这类文档的常见格式。最新版本的Doxygen（目前是1.5.2）统一采用UTF-8作为输出文件的编码格式，但微软的CHM编译工具不支持UTF-8，这就为制作中文CHM文档带来麻烦。本文提出了解决这个问题的方法。1 Doxygen简介1.1 要做什么使用Doxygen生成文档，主要是两件事：1. 写一个配置文件（Doxyfile）。一般用Doxywizard生成后，再手工修改。 2. 按照Doxygen的约定，将代码“文档化”。 然后只要执行命令：doxygen Doxyfile 就可以了。输入文件、输出目录、参数等都是在Doxyfile中配置的。1.2 得到什么Doxygen的输出格式主要有HTML、LATEX、RTF等： Doxygen在输出HTML文档时，可以自动准备用于制作CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）。用HTML Help Workshop中的CHM编译器（hhc.exe）编译后生成CHM文件。 Doxygen在输出LATEX文档的同时准备了转换到pdf格式的makefile。只要系统安装了合适的TEX工具，就可以从LATEX文档生成pdf文档。 Doxygen输出的RTF格式，已经针对Word作了优化，可以较好地转换到Word文档。 1.3 需要什么完成本文的范例需要以下工具：1. Doxygen的最新版本，可以从Doxygen的网站下载。 2. Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形，例如类的继承关系图、合作图，头文件包含关系图等。可以从Graphviz的网站下载Graphviz的最新版本。Doxygen使用了Graphviz的布局引擎dot，所以在文档中将其称作dot。 3. 为解决中文问题，需要使用Cygwin的iconv程序作编码转换。 4. 为解决中文问题，需要一个命令行的查找替换工具。我选择了白杨创作的工具fr。 可以从我的主页下载这些工具：Doxygen 1.5.2、Graphviz 2.12、iconv (GNU libiconv 1.9)和fr 20。2 CHM格式的中文问题前面说过：目前，Doxygen统一采用UTF-8作为输出文件的编码格式，但微软的CHM编译工具（hhc.exe）不支持UTF-8。如果直接用hhc.exe编译，中文不能正确显示。解决这个问题的思路很简单： 将Doxygen输出的html文件以及CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）全部转换到GBK编码后，再用hhc.exe编译即可。 可以用iconv对文件作编码转换。对于html文件，除了文件内容的编码转换外，还要将中的“UTF-8”替换成“gb2312”。2.1 用批处理简化操作我写了一些批处理文件（.bat）用于简化处理过程，包括：2.1.1 clean.bat 清空以前输出echo offecho 清空以前输出if exist refman.chm del /f /q refman.chmif exist outputhtml del /f /q outputhtml*.*if exist outputlatex del /f /q outputlatex*.*if exist outputrtf del /f /q outputrtf*.*if exist output del /f /q output*.*2.1.2 build.bat 调用doxygen生成文档echo offecho 生成文档doxygen Doxyfile2.1.3 utf82gbk.bat 将指定文件（支持通配符）从utf-8编码转换到gbk编码echo offecho 将%1从utf-8编码转换到gbk编码for %f in (%1) do copy %f %f.utf8for %f in (%1) do iconv -c -f utf-8 -t gbk %f.utf8 %f这个批处理文件要求系统当前路径上有iconv.exe。执行iconv时，使用-c参数忽略无法转换的字符。否则如果输入文件包含无法转换的字符，转换会失败。输入文件被备份到加过.utf8后缀的文件。2.1.4 html-utf82gbk.bat 将指定html文件（支持通配符）从utf-8编码转换到gbk编码echo offcall utf82gbk %1echo 将%1中的charset从UTF-8改为gb2312fr %1 -f:charset=UTF-8 -t:charset=gb2312这个批处理文件要求系统当前路径上有iconv.exe和白杨的fr.exe。2.1.5 makechm.bat 用Doxygen的输出制作chm文件echo offecho 将Doxygen输出文件编码从utf-8转换到gbkset path=%path%;%cd%cd outputhtmlecho 处理chm输入文件call utf82gbk.bat index.hhpcall utf82gbk.bat index.hhccall utf82gbk.bat index.hhkcall html-utf82gbk *.htmlecho 生成chm文件C:Program FilesHTML Help Workshophhc.exe index.hhpif exist index.chm copy index.chm .refman.chmdel /f /q *.chmcd .这个批处理文件假设系统在目录“C:Program FilesHTML Help Workshop”安装了“HTML Help Workshop”。并假设输出目录是Doxyfile所在目录的子目录output。2.1.6 rebuild.bat 重新生成chm文件echo offcall clean.batcall build.batcall makechm.bat2.2 小结了解DOS命令的朋友应该很容易看懂这些批处理吧。将这些批处理文件放在工作目录（即Doxyfile所在目录）后，每次只要键入rebuild就可以重新生成chm文件。必要时可以单独使用clean、build、makechm命令。utf82gbk和html-utf82gbk命令也可以单独使用。读者可以从我的主页下载这些批处理文件。3 创建配置文件3.1 准备工作“谁养鱼”是我最近写的一个小程序，它用推理法求解爱因斯坦谜题“谁养鱼”。读者可从穷举和推理：用C+程序求解“谁养鱼”下载未文档化的程序。制作文档前，我们要完成以下准备工作：1. 安装Doxygen、Graphviz和“HTML Help Workshop”。我使用的HTML Help Workshop版本是4.74.8702.0，英文版。网上有汉化版本，但运行时会出错。 2. 将iconv和fr程序放到系统路径包含的目录，例如c:windowssystem32。 3. 建立一个空目录fish，放入要注释的程序（fishsrc），建立制作文档的工作目录（fishdoc），将前面介绍的批处理文件放到doc目录。 好了，现在可以运行Doxywizard创建配置文件。可以直接点“Save.”按钮，将配置保存在docDoxyfile。这时，Doxyfile的内容是Doxygen的默认设置。Doxyfile是普通文本文件，我们可以直接打开编辑。不过在Doxywizard的界面上填写也很方便，每个参数都有详细提示。建议用Doxywizard完成第一次设置。以后如果需要调整个别参数，可以直接编辑Doxyfile。3.2 填写参数点“Expert.”按钮后，开始填写配置参数。:)，Doxygen是不是有很多参数？其实大多数参数都有缺省值，需要填写的不算多，下面分页介绍：3.2.1 Project页DOXYFILE_ENCODING是Doxyfile的文本编码。如果文件中有中文字符，可以填写GBK。填写项目名（PROJECT_NAME）、项目版本（PROJECT_NUMBER）、输出目录（OUTPUT_DIRECTORY）和输出语言（OUTPUT_LANGUAGE）。输出目录可以按Doxyfile的相对目录填写。输出语言相当于程序资源，选择Chinese。Doxywizard的中文支持不完善，中文字符会被存为乱码。我们直接编辑Doxyfile，填写：PROJECT_NAME = 谁养鱼取消FULL_PATH_NAMES。我们修改了以下参数：DOXYFILE_ENCODINGGBKPROJECT_NAME谁养鱼PROJECT_NUMBER1.0OUTPUT_DIRECTORYoutputOUTPUT_LANGUAGEChineseFULL_PATH_NAMESNO3.2.2 Messages页在Messages页将WARN_LOGFILE填写为build.log。这样，Doxygen会将编译时出现的警告和错误保存在build.log，我们可以对照修改。WARN_LOGFILEbuild.log3.2.3 Input页指定输入源文件目录（INPUT），将输入文件编码（INPUT_ENCODING）改为GBK。INPUT.srcINPUT_ENCODINGGBKFILE_PATTERNS参数是Doxygen要处理的文件类型，缺省值包括Doxygen支持的所有文件类型。不能用Doxygen文档化任意文件类型。例如Doxygen不支持汇编程序。3.2.4 Source Browser页选择SOURCE_BROWSER，在文档中包含源代码。SOURCE_BROWSERYES3.2.5 Html页选择GENERATE_HTMLHELP后，Doxygen会准备生成chm文件需要的项目文件、目录文件和索引文件。可以通过参数HTML_HEADER和HTML_FOOTER定制页面，参数值是包含定制内容的文件名。例如，我们可以建立文件html_foot，内容为：穷举和推理：用C+程序求解“谁养鱼”然后将HTML_FOOTER的值设为html_foot。GENERATE_HTMLHELPYESHTML_FOOTERhtml_foot3.2.6 LaTex页取消GENERATE_LATEX，不产生LaTex输出。GENERATE_LATEXNO3.2.7 Dot页在Dot页，可以选上UML_LOOK、CALL_GRAPH和CALLER_GRAPH。CALL_GRAPH是本函数调用其它函数的示意图，例如：CALLER_GRAPH是本函数调