doxygen配置及使用手册.doc

Doxygen安装及使用手册一 简介Doxygen可以从C，C+， java等源代码中提取消息来生成帮助文档， API资料等二 下载Doxygen以下，是在linux平台下的demo介绍。http:/www.stack.nl/dimitri/doxygen/index.html doxyen主页去下载doxygen-1.5.5.src.tar.gz三 Doxygen安装安装doxygen-1.5.5.src.tar.gz1 把下载好的doxygen-1.5.5.src.tar.gz拷到自己想要的目录中，我放到了自己的Home目录下。2 进入相应的目录：本例是在自己的home目录下3 解压 #tar -zxvf doxygen-1.5.5.src.tar.gz会在当前目录下生成一个名字为doxygen-1.5.5的目录。4 在自己的Home目录下建立一个doxygen目录，我们的doxygen以后就安装到这个目录下。 #mkdir doxygen5 进入doxygen-1.5.5目录#cd doxygen-1.5.56 安装：用prefix选项制定安装目录为/home/lvq/doxygen，lvq为我的用户名，这里可以用/doxygen代替。 #./configure prefix /doxygen #make #make install 这样在/doxygen 目录就安装好了doxygen软件7 生成配置文件 #cd /doxygen/bin/ # ./doxygen g 文件名 执行这个命令后就会生成一个制定名字的配置文件，这里我们不加文件名，只用./doxygen g 生成默认配置文件Doxyfile。四 如何使用Doxygen Doxygen可以从源代码中提取消息生成帮助文档，它是根据源代码中的特定注释来实现。所以，首先要给工程代码书写符合Doxygen格式的注释。1 以sipproxy小工程为例file档案的批注说明。author作者的信息brief用于class 或function的批注中，后面为class 或function的简易说明。param格式为param arg_name 参数说明主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。return后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。defgroup可以用这个注释格式给源代码文件分组retval格式为retval value 传回值说明主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。1) 这个工程在/home/lvq/self/sipproxy1/sipproxy-v1.04/目录下。这个代码是用C语言实现的。其中的多行注释形式为/* */，单行注释为/，对于其他语言注释形式略有不同。2) 以一个函数为例，说明如何书写注释 /* * brief process the received sip message, then send it to the remote client. * param buf a received sip message buffer. * retval return TRUE if it successes, else return FALSE. */int udp_process_message(char *precvstr)3) 因为一般一个工程项目中有很多模块，所以按模块分类显示效果会更好些。要生成模块需要特定的注释。以sipproxy为例，其中在sipproxy-v1.04/目录下又有两个子目录：layer2和layer3。Layer2/下面有main.c,file.c,file.h三个文件，layer3/下面有socket.c,socket.h两个文件。我们根据目录名生成两个模块。要实现这个功能，就要借助于注释格式defgroup，用它可以给源代码生成一个模块名.如下：在main.c中，用/* defgroup Layer2 */定义一个模块分组Layer2，再把其他两个文件file.c和file.h加入到这个分组中，可以用/* weakgroup File ingroup Layer2 */说明包含在Layer2模块中，/ 和 /对把要包含的代码加到这个分组中。用同样的方法给Layer3分组。2 配置文件DoxyfileSiproxy工程中的源代码已经注释好，但还必须合理配置文件Doxyfile（在安装的时候已经说明怎么生成此配置文件）。这里只配置需要的配置选项，其他配置选项，使用者可以根据自己的需要进行配置。 #vi /doxygen/bin/Doxyfile PROJECT_NAME = Sip Proxy （项目名称） PROJECT_NUMBER = 1.0 （相当于版本号） OUTPUT_DIRECTORY = /home/lvq/outputdoxygen (事先建好的目录，生成的帮助文档就在这个目录下，要用绝对路径) CREATE_SUBDIRS = YES (如果此项设成YES将会产生4096个子目录，可根据需要选择配置与否) OUTPUT_LANGUAGE = English (生成英文版文档) OPTIMIZE_OUTPUT_FOR_C = YES （C语言源代码程序专用） EXTRACT_ALL = YESSHOW_DIRECTORIES = YES （这样将展现路径层次） INPUT = /home/lvq/self/sipproxy1/sipproxy-v1.04/ (源代码所在路径) RECURSIVE = YES （搜索子目录） EXCLUDE = lib include （制定不搜索的子目录） EXCLUDE_PATTERNS = */lib/* */include/* （不分析这两个目录下的文件） SOURCE_BROWSER = NO （此项设置NO,将不包含源代码） GENERATE_TREEVIEW = YES （生成一个树状结构） PDF_HYPERLINKS = YES （生成PDF文件） USE_PDFLATEX = YES 配好之后，保存退出：按shift键 :（冒号）wq 3) 执行#./doxygen Doxyfile 执行成功后在outputdoxygen目录下生成两个目录：html和latex 4) 如果想生成PDF格式文件则进入outputdoxygen/latex下执行make命令：#cd /outputdoxygen/latex#make执行成功之后将生成PDF文件。5) 进入html目录，点击index.html，在浏览器上就会看到帮助文档。五 Doxygen配置知识扩展 PROJECT_NAMEProject 的名字，以一个单字为主，多个单字请使用双引号括住。PROJECT_VERSIONProject的版本号码。OUTPUT_DIRECTORY输出路径。产生的文件会放在这个路径之下。如果没有填这个路径，将会以目前所在路径来作为输出路径。OUTPUT_LANGUAGE输出语言。预设为English。1.2.16 版后，您可以使用Chinese-Traditional 来输出中文繁体的格式。INPUT指定加载或找寻要处理的程序代码档案路径。这边是一个表列式的型态。并且可指定档案及路径。举例来说若您有a.c, b.c, c.c 三个档案。您可使用INPUT = a.c, b.c, c.c 的方式。若您给定一个目录，该目录下面所有档案都会被处理。FILE_PATTERNS如果您的INPUT Tag 中指定了目录。您可以透过这个Tag来要求Doxygen在处理时，只针对特定的档案进行动作。例如：您希望对目录下的扩展名为.c, .cpp及.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h。 RECURSIVE这是一个布尔值的Tag，只接受YES或NO。当设定为YES时，INPUT所指定目录的所有子目录都会被处理。 EXCLUDE如果您有某几个特定档案或是目录，不希望经过Doxygen处理。您可在这个Tag中指定。 EXCLUDE_PATTERNS类似于FILE_PATTERNS的用法，只是这个Tag是供EXCLUDE所使用。SOURCE_BROWSER如果设定为YES，则Doxygen会产生出源文件的列表，以供查阅。INLINE_SOURCES如果设定为YES ，则程序代码也会被嵌入于说明文件中。 ALPHABETICAL_INDEX如果设定为YES，则一个依照字母排序的列表会加入在产生的文件中。GENERATE_HTML若设定为YES ，就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。 HTML_OUTPUTHTML文件的输出目录。这是一个相对路径，所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。 HTML_FILE_EXTENSIONHTML文件的扩展名。预设为.html。HTML_HEADER要使用在每一页HTML文件中的Header。如果没有指定，Doxygen会使用自己预设的Header。 HTML_FOOTER要使用在每一页HTML文件中的Footer。如果没有指定，Doxygen会使用自己预设的Footer。 HTML_STYLESHEET您可给定一个CSS 的设定，让HTML的输出结果更完美。GENERATE_HTMLHELP如设定为YES，Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。GENERATE_TREEVIEW若设定为YES，Doxygen会帮您产生一个树状结构，在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。TREEVIEW_WIDTH用来设定树状结构在画面上的宽度。GENERATE_LATEX设定为YES 时，会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX 的相关工具。 LATEX_OUTPUTLaTeX文件的输出目录，与HTML_OUTPUT用法相同，一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。 LATEX_CMD_NAMELaTeX程序的命令名称及档案所在。预设为latex。 GENERATE_RTF若设定为YES ，则会产生RTF 格式的说明档。RTF_OUTPUT与HTML_OUTPUT 用法相同，用来指定RTF 输出档案路径。预设为rtf。GENERATE_MAN若设定为YES ，则会产生Unix Man Page 格式的说明文件。MAN_OUTPUT与HTML_OUTPUT 用法相同，用来指定Man Page的输出目录。预设为man。GENERATE_XML若设定为YES ，则会产生XML 格式的说明文件。ENABLE_PREPROCESSING若设定为YES ，则Doxygen 会激活C 的前置处理器来处理原始档。 PREDEFINED可以让您自行定义一些宏。类似于gcc 中的-D选项。 1 进入doxygen安装目录 #cd /doxygen 2 进入doxygen下的bin/目录 #cd bin/ 3 生成先doxygen -g来生成一个Doxygen配置文件,在该配置文件里设置一些选项，doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释#开始；tag = value ,value2；对于多值的情况可以使用 tag += value ,value2。对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。TAG缺省值含义PROJECT_NAME项目名称 (我的例子项目名称为sipproxy)PROJECT_NUMBER可以理解为版本信息(1.0)OUTPUT_DIRECTORY输出文件到的目录，相对目录（doxygen运行目录）或者绝对目录(/outputdoxygen)INPUT代码文件或者代码所在目录，使用空格分割FILE_PATTERNS*.c *.cc *.cxx *.cpp *.c+ *.java *.ii *.ixx *.ipp *.i+ *.inl *.h *.hh *.hxx *.hpp *.h+ *.idl *.odl指定INPUT的目录中特定文件，如：*.cpp *.c *.h RECURSIVENO是否递归INPUT中目录的子目录EXCLUDE在INPUT目录中需要忽略的子目录(这里排除lib和include目录，填写：lib include)EXCLUDE_PATTERNS明确指定的在INPUT目录中需要忽略的文件，如：*/include/* */lib/*OUTPUT_LANGUAGEEnglish生成文档的语言，当前支持2、30种语言，国内用户可以设置为ChineseUSE_WINDOWS_ENCODINGYES（win版本）NO（unix版本）编码格式，默认即可。EXTRACT_ALLNO为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释。类的私有成员和所有的静态项由EXTRACT_PRIVATE和 EXTRACT_STATIC控制EXTRACT_PRIVATENO是否解析类的私有成员EXTRACT_STATICNO是否解析静态项EXTRACT_LOCAL_CLASSESYES是否解析源文件（cpp文件）中定义的类SOURCE_BROWSERNO如果为YES，源代码文件会被包含在文档中INLINE_SOURCESNO如果为YES，函数和类的实现代码被包含在文档中PDF_HYPERLINKS 标志设置成YES, 想生成PDF文件ALPHABETICAL_INDEXNO生成一个字母序的列表，有很多类、结构等项时建议设为YESGENERATE_HTMLYES是否生成HTML格式文档GENERATE_HTMLHELPNO是否生成压缩HTML格式文档（.chm）GENERATE_LATEXYES是否乘车latex格式的文档GENERATE_RTFNO是否生成RTF格式的文档GENERATE_MANNO是否生成man格式文档GENERATE_XMLNO是否生成XML格式文档六Doxygen注释知识扩展1 doxygen注释1.1 注释风格 下面是工作量最大部分，安装doxygen格式写注释。通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两部分都是可选的。可以有多种方式标识出doxygen可识别的注释块。1）JavaDoc类型的多行注释。/* .text.*/2）QT样式的多行注释。/*!.text.*/3） / text.4） /! text.简要说明有多种方式标识，这里推荐使用brief命令强制说明，例如：/* brief some brief description * brief description more. * * some more detailed description*/以上这些注释格式用来对紧跟其后的代码进行注释。doxygen也允许把注释放到代码后面，具体格式是放一个到注释开始部分。例如：int var1 ; /* .text. */int var2; / .text.注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。1.2 doxygen常用注释格式通常的选择上面的一、两种注释风格，遇到头文件中各种类型定义，关键变量、宏的定义，在其前或者后使用 brief 定义其简要说明，空一行后继续写其详细的注释即可。对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下：/*brief funcs brief comment.* Some detailed comment.*param a param a s comment.*param b param b s comment.*exception std:out_of_range exceptions comment.*return returns comment.*/int func1(int a, int b);进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。/* group_name brief group description * detailed group description * */code/* */group中的代码可以有自己的注释。单纯定义一个模块，去除 和命令即可。任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup命令即可。Group之间使用ingroup命令，可以组成树状关系。/* file util.cpp * ingroup group_name* brief files brief info.*/把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：/* Comments for all below code. */code/对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：/* name group_name* description for group.*/code/1.3 doxygen常用注释命令doxygen通过注释命令识别注释中需要特殊处理的注释，比如函数的参数、返回值进行突出显示。上面也提到了一些注释命令（如：brief、param、return、以及group相关的命令），下面对其他一些常用的注释命令进行解释说明。exception exception description对一个异常对象进行注释。warning warning message 一些需要注意的事情todo things to be done 对将要做的事情进行注释see comment with reference to other items 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。relates 通常用做把非成员函数的注释文档包含在类的说明文档中。since text 通常用来说明从什么版本、时间写此部分代码。deprecatedpre description of the precondition 用来说明代码项的前提条件。post description of the postcondition 用来说明代码项之后的使用条件。code 在注释中开始说明一段代码，直到endcode命令。endcode 注释中代码段的结束。到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。1.4 注释的书写 注释应该怎么写，写多还是写少。过多的注释甚至会干扰对代码的阅读。写注释的一个总的原则就是注释应该尽量用来表明作者的意图，至少也应该是对一部分代码的总结，而不应该是对代码的重复或者解释。对代码的重复或者解释的代码，看代码可能更容易理解。反映作者意图的注释解释代码的目的，从解决问题的层次上进行注释，而代码总结性注释则是从问题的解答的层次上进行注释。推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点：避免对单独语句进行注释；通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；对读者可能会有疑问的地方进行注释；对数据定义进行注释，而不是对其使用过程进行注释；对于难于理解的代码，进行改写，而不要试图通过注释加以说明；对关键的控制结构进行注释；对数据和函数的边界、使用前提等进行注释；1.5Modules模块Modules是一种归组things在分离的page上的方式。组的成员可以是file，namespace，classes，functions，variables，enums，typedefs和defines，但也可以是其他groups。要定义一个group，应该在一个特殊注释块放置defgroup。命令的第一个参数应该是唯一标志该group的标签。要将一个entity归为某个group的一个member，在entity前放置ingroup命令。第二个参数是group的title。要避免在注释中每个member前放置ingroup命令，可以将member用和封装起来。标记可以放置group的注释中，也可以在一个独立的注释块使用这些group的标记符号groups也可以嵌套。如果多次使用一个group标签，将会出错。如果不希望doxygen强行执行唯一标签，可以使用addtogroup而非defgroup。运作方式和defgroup很像，但是如果该group已经定义，它默认向已存在的注释中添加一个新的项。Group的title对此命令是可选的，也可以考虑使用它。/* addtogroup */*/*/这样可以在其他地方以更加详细的说明添加members到一个group注意compound entities（例如classes，files和namespaces）可以放在多个groups中，但是members（例如variables，functions，typedefs和enmus）只可以归于一个group（这个限制是为了避免链接目标的ambiguous）。Doxygen将members放在有最高优先级的gourp之中：f.i. ingroup高于任何使用的自动归组。和同等的优先级group定义冲突将触发一个警告，除非one definition was for a member without any explicit documentation。下面的例子将VarInA放在group A中，并默认将IntegerVariable放入group IntVariables解决和IntegerVariable的冲突，因为IntegerVariable的第二个instance是未作注释的：/* * ingroup A */extern int VarInA;/* * defgroup IntVariables Global integer variables */*/* an integer variable */extern int IntegerVariable;/*/./* * defgroup Variables Global variables */*/* a variable in group A */int VarInA;int IntegerVariable;/*/Group定义命令的优先级（从高到低）：ingroup，defgroup，addtogroup，weakgroup。而weakgroup很像一个有低优先级的addtogroup。它被设计为实现一个“lazy”的group定义方法：可以在.h文件中使用高优先级来定义结构，在.cpp文件中使用weakgroup这样不会重复.h文件中的层次结构。（译注：是否就是说，还可以这样的话还可以在.cpp文件中再作一次group动作？例如，在.cpp文件中又定义了几个nonmember functions，这时可以将使用nonmember function和以前尽管在.h已经做了group的member functions放在一起。）Example: /* defgroup group1 The First Group * This is the first group * */* brief class C1 in group 1 */class C1 ;/* brief class C2 in group 1 */class C2 ;/* function in group 1 */void func() /* */ / end of group1/* * defgroup group2 The Second Group * This is the second group */* defgroup group3 The Third Group * This is the third group */* defgroup group4 The Fourth Group * ingroup group3 * Group 4 is a subgroup of group 3 */* * ingroup group2 * brief class C3 in group 2 */class C3 ;/* ingroup group2 * brief class C4 in group 2 */class C4 ;/* ingroup group3 * brief class C5 in link group3 the third groupendlink. */class C5 ;/* ingroup group1 group2 group3 group4 * namespace N1 is in four groups * sa link group1 The first groupendlink, group2, group3, group4 * * Also see ref mypage2 */namespace N1 ;/* file * ingroup group3 * brief this file in group 3 */* defgroup group5 The Fifth Group * This is the fifth group * */* page mypage1 This is a section in group 5 * Text of the first section */* page mypage2 This is another section in group 5 * Text of the second section */* */ / end of group5/* addtogroup group1 * * More documentation for the first group. * */* another function in group 1 */void func2() /* yet another function in group 1 */void func3() /* */ / end of group1Click here for the corresponding HTML documentation that is generated by Doxygen. Member Groups如果一个compound（例如一个class或file）有多个members，通常我们希望将其group。Doxygen已经可以自动按照类型和protection级别将这些things归组在一起，但可能你会认为仅仅这样是不够的或者这种缺省的方法是错误的。例如你认为有不同（语法）的类型需要归入同一个group（语意）。这样定义一个member group：/ ./块或者使用/*/ . /*/ 块如果你更喜欢C style注释。需要注意的是所有的members必须写在其中。在/之前还可以加一个注释块，这个注释块应该包含name（