学习用 doxygen 生成源码文档格式.docx
- 文档编号:18075658
- 上传时间:2022-12-13
- 格式:DOCX
- 页数:15
- 大小:26.96KB
学习用 doxygen 生成源码文档格式.docx
《学习用 doxygen 生成源码文档格式.docx》由会员分享,可在线阅读,更多相关《学习用 doxygen 生成源码文档格式.docx(15页珍藏版)》请在冰豆网上搜索。
svn
实用程序下载源代码。
回页首
使用doxygen生成文档
使用doxygen生成源代码的文档需要执行三个步骤。
生成配置文件
在shell提示上,输入命令
doxygen-g
。
这个命令在当前目录中生成一个可编辑的配置文件
Doxyfile。
可以改变这个文件名,在这种情况下,应该调用
doxygen-g<
user-specifiedfilename>
,见
清单2。
清单2.生成默认的配置文件
bash-2.05b$doxygen-g
Configurationfile'
Doxyfile'
created.
Nowedittheconfigurationfileandenter
doxygenDoxyfile
togeneratethedocumentationforyourproject
bash-2.05b$lsDoxyfile
Doxyfile
编辑配置文件
配置文件采用
<
TAGNAME>
=
VALUE>
这样的结构,与Make文件格式相似。
下面是最重要的标记:
∙<
OUTPUT_DIRECTORY>
:
必须在这里提供一个目录名,例如/home/user1/documentation,这个目录是放置生成的文档文件的位置。
如果提供一个不存在的目录名,doxygen会以这个名称创建具有适当用户权限的目录。
INPUT>
这个标记创建一个以空格分隔的所有目录的列表,这个列表包含需要生成文档的
源代码文件和头文件。
例如,请考虑以下代码片段:
INPUT=/home/user1/project/kernel/home/user1/project/memory
在这里,doxygen会从这两个目录读取
源代码。
如果项目只有一个源代码根目录,其中有多个子目录,那么只需指定根目录并把
RECURSIVE>
标记设置为
Yes。
FILE_PATTERNS>
在默认情况下,doxygen会搜索具有典型
扩展名的文件,比如
.c、.cc、.cpp、.h
和
.hpp。
如果
标记没有相关联的值,doxygen就会这样做。
如果源代码文件采用不同的命名约定,就应该相应地更新这个标记。
例如,如果项目使用
.c86
作为
C
文件扩展名,就应该在
标记中添加这个扩展名。
如果源代码层次结构是嵌套的,而且需要为所有层次上的
文件生成文档,就把这个标记设置为Yes。
例如,请考虑源代码根目录层次结构/home/user1/project/kernel,其中有/home/user1/project/kernel/vmm和/home/user1/project/kernel/asm等子目录。
如果这个标记设置为
Yes,doxygen就会递归地搜索整个层次结构并提取信息。
EXTRACT_ALL>
这个标记告诉doxygen,即使各个类或函数没有文档,也要提取信息。
必须把这个标记设置为
EXTRACT_PRIVATE>
把这个标记设置为
否则,文档不包含类的私有数据成员。
EXTRACT_STATIC>
否则,文档不包含文件的静态成员(函数和变量)。
清单3
给出一个Doxyfile示例。
清单3.包含用户提供的标记值的doxyfile示例
OUTPUT_DIRECTORY=/home/user1/docs
EXTRACT_ALL=yes
EXTRACT_PRIVATE=yes
EXTRACT_STATIC=yes
INPUT=/home/user1/project/kernel
#Donotaddanythinghereunlessyouneedto.Doxygenalreadycoversall
#commonformatslike.c/.cc/.cxx/.c++/.cpp/.inl/.h/.hpp
FILE_PATTERNS=
RECURSIVE=yes
运行doxygen
在shell提示下输入
doxygenDoxyfile(或者已为配置文件选择的其他文件名)运行doxygen。
在最终生成HypertextMarkupLanguage(HTML)和Latex格式(默认)的文档之前,doxygen会显示几个消息。
在生成文档期间,在
标记指定的文件夹中,会创建两个子文件夹
html
latex。
清单4
是一个doxygen运行日志示例。
清单4.doxygen的日志输出
Searchingforincludefiles...
Searchingforexamplefiles...
Searchingforimages...
Searchingfordotfiles...
Searchingforfilestoexclude
Readinginputfiles...
Readingandparsingtagfiles
Preprocessing/home/user1/project/kernel/kernel.h
…
Read12489207bytes
Parsinginput...
Parsingfile/project/user1/project/kernel/epico.cxx
Freeinginput...
Buildinggrouplist...
..
GeneratingdocsforcompoundMemoryManager:
:
ProcessSpec
Generatingdocsfornamespacestd
Generatinggroupindex...
Generatingexampleindex...
Generatingfilememberindex...
Generatingnamespacememberindex...
Generatingpageindex...
Generatinggraphinfopage...
Generatingsearchindex...
Generatingstylesheet...
文档输出格式
除了HTML之外,doxygen还可以生成几种输出格式的文档。
可以让doxygen生成以下格式的文档:
∙UNIX手册页:
把
GENERATE_MAN>
在默认情况下,会在
指定的目录中创建
man
子文件夹,生成的文档放在这个文件夹中。
必须把这个文件夹添加到MANPATH环境变量中。
∙RichTextFormat(RTF):
GENERATE_RTF>
RTF_OUTPUT>
标记设置为希望放置.rtf文件的目录;
在默认情况下,文档放在OUTPUT_DIRECTORY中的
rtf
子文件夹中。
要想支持跨文档浏览,应该把<
RTF_HYPERLINKS>
如果设置这个标记,生成的.rtf文件会包含跨文档链接。
∙Latex:
在默认情况下,doxygen生成Latex和HTML格式的文档。
在默认的Doxyfile中,<
GENERATE_LATEX>
另外,<
LATEX_OUTPUT>
标记设置为Latex,这意味着会在OUTPUT_DIRECTORY中创建
latex
子文件夹并在其中生成Latex文件。
∙Microsoft®
CompiledHTMLHelp(CHM)格式:
GENERATE_HTMLHELP>
因为在UNIX平台上不支持这种格式,doxygen只在保存HTML文件的文件夹中生成一个
index.hhp
文件。
您必须通过HTML帮助编译器把这个文件转换为.chm文件。
∙ExtensibleMarkupLanguage(XML)格式:
GENERATE_XML>
(注意,doxygen开发团队还在开发XML输出)。
清单5
提供的Doxyfile示例让doxygen生成所有格式的文档。
清单5.生成多种格式的文档的Doxyfile
#forHTML
GENERATE_HTML=YES
HTML_FILE_EXTENSION=.htm
#forCHMfiles
GENERATE_HTMLHELP=YES
#forLatexoutput
GENERATE_LATEX=YES
LATEX_OUTPUT=latex
#forRTF
GENERATE_RTF=YES
RTF_OUTPUT=rtf
RTF_HYPERLINKS=YES
#forMANpages
GENERATE_MAN=YES
MAN_OUTPUT=man
#forXML
GENERATE_XML=YES
doxygen中的特殊标记
doxygen包含几个特殊标记。
C/C++代码的预处理
为了提取信息,doxygen必须对
代码进行预处理。
但是,在默认情况下,它只进行部分预处理——计算条件编译语句(#if…#endif),但是不执行宏展开。
请考虑
清单6
中的代码。
清单6.使用宏的C++代码示例
#include<
cstring>
rope>
#defineUSE_ROPE
#ifdefUSE_ROPE
#defineSTRINGstd:
rope
#else
string
#endif
staticSTRINGname;
通过源代码中定义的
USE_ROPE>
,doxygen生成的文档如下:
Defines
#defineUSE_ROPE
Variables
staticSTRINGname
在这里可以看到doxygen执行了条件编译,但是没有对
STRING
执行宏展开。
Doxyfile中的
ENABLE_PREPROCESSING>
标记在默认情况下设置为
为了执行宏展开,还应该把
MACRO_EXPANSION>
这会使doxygen产生以下输出:
staticstd:
ropename
如果把
No,前面源代码的doxygen输出就是:
Variables
注意,文档现在没有定义,而且不可能推导出
的类型。
因此,总是应该把
标记设置为Yes。
在文档中,可能希望只展开特定的宏。
为此,除了把
Yes之外,还必须把
EXPAND_ONLY_PREDEF>
Yes(这个标记在默认情况下设置为
No),并在
PREDEFINED>
或<
EXPAND_AS_DEFINED>
标记中提供宏的细节。
清单7
中的代码,这里只希望展开宏
CONTAINER。
清单7.包含多个宏的C++源代码
#ifALLOW_RANDOM_ACCESS==1
#defineCONTAINERstd:
vector
list
staticCONTAINERgList;
清单8
给出配置文件。
清单8.允许有选择地展开宏的Doxyfile
ENABLE_PREPROCESSING=YES
MACRO_EXPANSION=YES
EXPAND_ONLY_PREDEF=YES
EXPAND_AS_DEFINED=CONTAINER
下面的doxygen输出只展开了
CONTAINER:
#defineSTRINGstd:
string
#defineCONTAINERstd:
staticSTRINGname
staticstd:
listgList
注意,只有
CONTAINER
宏被展开了。
在
都设置为
Yes
的情况下,<
标记只选择展开等号操作符右边列出的宏。
对于预处理过程,要注意的最后一个标记是
就像用
-D
开关向C++编译器传递预处理器定义一样,使用这个标记定义宏。
清单9
中的Doxyfile。
清单9.定义了宏展开标记的Doxyfile
EXPAND_AS_DEFINED=
PREDEFINED=USE_ROPE=\
ALLOW_RANDOM_ACCESS=1
下面是doxygen生成的输出:
#defineUSE_CROPE
rope
ropename
vectorgList
在使用
标记时,宏应该定义为
macroname>
=<
value>
形式。
如果不提供值,比如简单的
#define,那么只使用
spaces>
即可。
多个宏定义以空格或反斜杠(\)分隔。
从文档生成过程中排除特定文件或目录
在Doxyfile中的
EXCLUDE>
标记中,添加不应该为其生成文档的文件或目录(以空格分隔)。
因此,如果提供了源代码层次结构的根,并要跳过某些子目录,这将非常有用。
例如,如果层次结构的根是src_root,希望在文档生成过程中跳过examples/和test/memoryleaks文件夹,Doxyfile应该像
清单10
这样。
清单10.使用EXCLUDE标记的Doxyfile
INPUT=/home/user1/src_root
EXCLUDE=/home/user1/src_root/examples/home/user1/src_root/test/memoryleaks
生成图形和图表
在默认情况下,Doxyfile把
CLASS_DIAGRAMS>
这个标记用来生成类层次结构图。
要想生成更好的视图,可以从
Graphviz下载站点
下载dot工具。
Doxyfile中的以下标记用来生成图表:
在Doxyfile中这个标记默认设置为
No,就不生成继承层次结构图。
HAVE_DOT>
Yes,doxygen就使用dot工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。
注意,如果这个标记设置为
Yes,<
标记就无效了。
CLASS_GRAPH>
标记和这个标记同时设置为
Yes,就使用
dot
生成继承层次结构图,而且其外观比只使用
时更丰富。
COLLABORATION_GRAPH>
Yes,doxygen会生成协作图(还有继承图),显示各个类成员(即包含)及其继承层次结构。
清单11
提供一个使用一些数据结构的示例。
注意,在配置文件中
、<
和<
标记都设置为
清单11.C++类和结构示例
structD{
intd;
};
classA{
inta;
classB:
publicA{
intb;
classC:
publicB{
intc;
Dd;
图1
给出doxygen的输出。
图1.使用dot工具生成的类继承图和协作图
代码文档样式
到目前为止,我们都是使用doxygen从原本没有文档的代码中提取信息。
但是,doxygen也鼓励使用文档样式和语法,这有助于生成更详细的文档。
本节讨论doxygen鼓励在
代码中使用的一些常用标记。
更多信息参见
参考资料。
每个代码元素有两种描述:
简短的和详细的。
简短描述通常是单行的。
函数和类方法还有第三种描述体内描述(in-bodydescription),这种描述把在函数体中找到的所有注释块集中在一起。
比较常用的一些doxygen标记和注释样式如下:
∙简短描述:
使用单行的
C++
注释,或使用
\brief>
标记。
∙详细描述:
使用JavaDoc式的注释
/**…test…*/(注意开头的两个星号[*])或Qt式的注释
/*!
…text…*/。
∙体内描述:
类、结构、联合体和名称空间等
元素都有自己的标记,比如
\class>
\struct>
\union>
\namespace>
为了为全局函数、变量和枚举类型生成文档,必须先对对应的文件使用
\file>
清单12
给出的示例包含用于四种元素的标记:
函数标记(<
\fn>
)、函数参数标记(<
\param>
)、变量名标记(<
\var>
)、用于
#define
的标记(<
\def>
)以及用来表示与一个代码片段相关的问题的标记(<
\warning>
)。
清单12.典型的doxygen标记及其使用方法
\fileglobaldecls.h
\briefPlacetolookforglobalvariables,enums,functions
andmacrodefinitions
*/
/**\varconstintfileSize
\briefDefaultsizeofthefileondisk
constintfileSize=1048576;
/**\defSHIFT(value,length)
\briefLeftshiftvaluebylengthinbits
#defineSHIFT(value,length)((value)<
(length))
/**\fnboolcheck_for_io_errors(FILE*fp)
\briefChecksifafileiscorruptedornot
\paramfpPointertoanalreadyopenedfile
\warningNotthreadsafe!
boolcheck_for_io_errors(FILE*fp);
下面是生成的文档:
(l
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 学习用 doxygen 生成源码 习用 生成 源码