doxygen的简要用法Word文档格式.docx

doxygen的简要用法Word文档格式.docx

《doxygen的简要用法Word文档格式.docx》由会员分享，可在线阅读，更多相关《doxygen的简要用法Word文档格式.docx（20页珍藏版）》请在冰点文库上搜索。

*–r读取

*–w可写

*–a添加

*–t文本模式（不能与b联用）

*–b二进制模式（不能与t联用）

*@return返回文件编号

*–-1表示打开文件失败

*@note文件打开成功后，必须使用:

CloseFile函数关闭

*@par示例:

*@code

//用文本只读方式打开文件

intf=OpenFile（”d:

\\test.txt”,“rt”）;

*@endcode

*@see:

ReadFile:

WriteFile:

CloseFile

*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。

intOpenFile（constchar*file_name,constchar*file_mode）;

5.枚举类型定义

/**枚举常量*/

typedefenumTDayOfWeek

{

SUN=0,/**<

星期天（注意，要以“<

”小于号开头）*/

MON=1,/**<

星期一*/

TUE=2,/**<

星期二*/

WED=3,/**<

星期三*/

THU=4,/**<

星期四*/

FRI=5,/**<

星期五*/

SAT=6/**<

星期六*/

}

/**定义类型TEnumDayOfWeek*/

TEnumDayOfWeek;

6.项目符号标记

*Alistofevents:

*–mouseevents

*-#mousemoveevent

*-#mouseclickevent\n

*Moreinfoabouttheclickevent.

*-#mousedoubleclickevent

*–keyboardevents

*-#keydownevent

*-#keyupevent

*

*Moretexthere.

结果为：

Alistofevents:

∙mouseevents

1.mousemoveevent

2.mouseclickevent

Moreinfoabouttheclickevent.

3.mousedoubleclickevent

∙keyboardevents

4.keydownevent

5.keyupevent

Moretexthere.

代码示范：

*@defgroupEXAMPLES自动注释文档范例

*@authorminidxer

*@version1.0

*@date2007-2008

*@name文件名常量

/**日志文件名*/

#defineLOG_FILENAME“c:

\\log\\debug.log”

/**数据文件名*/

#defineDATA_FILENAME“c:

\\data\\detail.dat”

/**存档文件名*/

#defineBAK_FILENAME“c:

\\data\\backup.dat”

/**@}*///文件名常量

*@name系统状态常量

*/

/**正常状态*/

#defineSYS_NORMAL0

/**故障状态*/

#defineSYS_FAULT1

/**警告状态*/

#defineSYS_WARNNING2

/**@}*///系统状态常量

星期天*/

星期一*/

星期二*/

星期三*/

星期四*/

星期五*/

星期六*/

/**定义类型PEnumDayOfWeek*/

typedefTEnumDayOfWeek*PEnumDayOfWeek;

/**定义枚举变量enum1*/

TEnumDayOfWeekenum1;

/**定义枚举指针变量enum2*/

PEnumDayOfWeekp_enum2;

*@defgroupFileUtils文件操作函数

*–-1表示打开文件失败

intf=OpenFile（”c:

*@endcode

*读取文件

*@param[in]file文件编号，参见：

OpenFile

*@param[out]buffer用于存放读取的文件内容

*@param[in]len需要读取的文件长度

*@return返回读取文件的长度

*–-1表示读取文件失败

*@pre\efile变量必须使用:

OpenFile返回值

*@pre\ebuffer不能为NULL

OpenFile:

intReadFile（intfile,char*buffer,intlen）;

*写入文件

*@param[in]buffer用于存放将要写入的文件内容

*@param[in]len需要写入的文件长度

*@return返回写入的长度

*–-1表示写入文件失败

intWriteFile（intfile,constchar*buffer,intlen）;

*关闭文件

*@paramfile文件编号，参见：

*@retval0为成功

*@retval-1表示失败

ReadFile

intCloseFile（intfile）;

/**@}*///文件操作函数

/**@}*///自动注释文档范例

Doxygen简单经验谈。

。

Doxygen，大名鼎鼎的文档生成工具，被Boost、OpenCasCade等诸多项目作为文档生成的不二人选。

人说，才华横溢往往是高深莫测，这句话放在Doxygen这里显然是不适用的。

十八般武艺样样精通的Doxygen，却十分的简单易用，从头到尾看一下它随机的文档，想不会用都难。

嫌看英文麻烦的，这里有一篇中文的入门介绍。

简单的说，如果你准备在项目中采用Doxygen作为文档生成的工具，首先，你需要了解，Doxygen需要什么样的代码结构才能够生产文档。

Doxygen基本上对光秃秃的代码不感兴趣，你需要在所有的类、函数、成员函数、公共变量、名字空间等代码已有表示的结构上方添加上指定格式的注释，Doxygen才能识别出来。

此外，你还可以按照指定格式的注释添加附加的信息，用以生成模块的分类，架构图之类的信息。

Doxygen支持的注释格式多种多样，强烈建议制定一个统一的标准，否则会给项目中其他的人员或者后来的人员带来很多的困扰。

按照指定的格式书写了注释之后，就需要写一个Doxygen的配置文件，依照此配置文件，Doxygen可以生产HTML、Tex、XML等多种格式输出文档。

Doxygen的配置文件，有辅助的GUI工具帮助书写，你只需要改几个选项，点几下按钮就信手拈来了。

但在此强烈建议，你应该把Doxygen每一个配置值的含义都了解一下，写一些简单的例子实践一下，这样一则你可以清楚的明白你需要的格式该如何配置出来，二则你可以充分了解Doxygen可以做到什么程度，以备不时之需。

Doxygen通常是用作生成英文文档的，生成中文文档需要修改输入和输出的码制，这样可以改变解析方式，生成中文文档。

但是，你必须意识到，Doxygen在从注释中抽取信息是需要做语法解析的，这些解析都是基于英文的基础，不可能在这个层面上支持中文。

比如，一个类的简明信息和详细信息的分隔，是通过英文的句号“.”来识别的，如果你用中文的句号“。

”，Doxygen就分辨不出来了。

再比如，在某个类的注释中，你写Createdbyxxxfunction，其中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列表对项目进行简单的管理。

比如，有一个类你有一些后续的工作没有完成，你可以在其注释中加上@todoxxx，（这只是其中一种语法，不是唯一的规范...）Doxygen会将其链接添加到一个todolist中，并为该todolist生成一个页面，查看起来颇为方便。

同样，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文档带来麻烦。

本文提出了解决这个问题的方法。

1Doxygen简介

1.1要做什么

使用Doxygen生成文档，主要是两件事：

1.写一个配置文件（Doxyfile）。

一般用Doxywizard生成后，再手工修改。

2.按照Doxygen的约定，将代码“文档化”。

然后只要执行命令：

doxygenDoxyfile

就可以了。

输入文件、输出目录、参数等都是在Doxyfile中配置的。

1.2得到什么

Doxygen的输出格式主要有HTML、LATEX、RTF等：

∙Doxygen在输出HTML文档时，可以自动准备用于制作CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）。

用HTMLHelpWorkshop中的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。

可以从我的主页下载这些工具：

Doxygen1.5.2、Graphviz2.12、iconv（GNUlibiconv1.9）和fr2.1.1.120。

2CHM格式的中文问题

前面说过：

目前，Doxygen统一采用UTF-8作为输出文件的编码格式，但微软的CHM编译工具（hhc.exe）不支持UTF-8。

如果直接用hhc.exe编译，中文不能正确显示。

解决这个问题的思路很简单：

∙将Doxygen输出的html文件以及CHM的项目文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）全部转换到GBK编码后，再用hhc.exe编译即可。

可以用iconv对文件作编码转换。

对于html文件，除了文件内容的编码转换外，还要将

<

metahttp-equiv="

Content-Type"

content="

text/html;

charset=UTF-8"

>

中的“UTF-8”替换成“gb2312”。

2.1用批处理简化操作

我写了一些批处理文件（.bat）用于简化处理过程，包括：

2.1.1clean.bat——清空以前输出

@echooff

echo清空以前输出

ifexistrefman.chmdel/f/qrefman.chm

ifexistoutput\htmldel/f/qoutput\html\*.*

ifexistoutput\latexdel/f/qoutput\latex\*.*

ifexistoutput\rtfdel/f/qoutput\rtf\*.*

ifexistoutputdel/f/qoutput\*.*

2.1.2build.bat——调用doxygen生成文档

echo生成文档

doxygenDoxyfile

2.1.3utf82gbk.bat——将指定文件（支持通配符）从utf-8编码转换到gbk编码

echo将%1从utf-8编码转换到gbk编码

for%%fin（%1）docopy%%f%%f.utf8

for%%fin（%1）doiconv-c-futf-8-tgbk%%f.utf8>

%%f

这个批处理文件要求系统当前路径上有iconv.exe。

执行iconv时，使用-c参数忽略无法转换的字符。

否则如果输入文件包含无法转换的字符，转换会失败。

输入文件被备份到加过.utf8后缀的文件。

2.1.4html-utf82gbk.bat——将指定html文件（支持通配符）从utf-8编码转换到gbk编码

callutf82gbk%1

echo将%1中的charset从UTF-8改为gb2312

fr%1-f:

charset=UTF-8-t:

charset=gb2312

这个批处理文件要求系统当前路径上有iconv.exe和白杨的fr.exe。

2.1.5makechm.bat——用Doxygen的输出制作chm文件

echo将Doxygen输出文件编码从utf-8转换到gbk

setpath=%path%;

%cd%

cdoutput\html

echo处理chm输入文件

callutf82gbk.batindex.hhp

callutf82gbk.batindex.hhc

callutf82gbk.batindex.hhk

callhtml-utf82gbk*.html

echo生成chm文件

"

C:

\ProgramFiles\HTMLHelpWorkshop\hhc.exe"

index.hhp

ifexistindex.chmcopyindex.chm..\..\refman.chm

del/f/q*.chm

cd..\..

这个批处理文件假设系统在目录“C:

\ProgramFiles\HTMLHelpWorkshop\”安装了“HTMLHelpWorkshop”。

并假设输出目录是Doxyfile所在目录的子目录output。

2.1.6rebuild.bat——重新生成chm文件

callclean.bat

callbuild.bat

callmakechm.bat

2.2小结

了解DOS命令的朋友应该很容易看懂这些批处理吧。

将这些批处理文件放在工作目录（即Doxyfile所在目录）后，每次只要键入rebuild就可以重新生成chm文件。

必要时可以单独使用clean、build、makechm命令。

utf82gbk和html-utf82gbk命令也可以单独使用。

读者可以从我的主页下载这些批处理文件。

3创建配置文件

3.1准