doxygen系列问题

OO~ posted @ 2013年5月15日 22:13 in 其他 , 2098 阅读

  Doxygen是一个比较强大的、针对源代码的开源文档生成系统,其适用的语言有C++、C、Java、Objective-C、Pyhon、IDL、Fortan、VHDL、PHP、C#以及D语言。现有很多开源项目都使用到了doxygen。它的出现使得文档的维护工作大大简化,只需要根据一定的规则的注释,就可以生成质量比较搞的文档。现在的doygen能支持一般的操作系统,如windows、unix、Mac等等。

  下面对doxygen作进一步的分析:

一、安装

  由于我使用的是linux系统,所以,整个文章的内容都是关于doxygen在linxu下的使用;在linux下,doxygen的安装如下:

sudo apt-get install doxygen

  真正在使用上windows下的doxygen还是比较直观的,应该更适合一些人群,因为有GUI界面供使用,网上的教程也很多。

二、基本使用:

1. 生成配置文件:(filename是相应的配置文件名,如果缺省,默认是Doxyfile):

doxygen -g filename

2.修改配置文件:

  这里说一些我认为比较重要的几处,其他的可以根据相应的选择进行设置(其实在配置文档的注释中,各项已经非常明朗了)。

PROJECT_NAME 写入你的项目名称,在生成的时候会涉及到 默认为"my project"
PROJECT_NUMBER 指的是你工程的版本号 可以选择不写
OUTPUT_DIRECTORY 最后输出的目录选择,例如"./doc/" 如果不写,默认是当前目录
JAVADOC_AUTOBRIEF 修改成YES,表示支持java的注释格式 默认是NO,在代码中,总要设置几个注释规范
MULTILINE_CPP_IS_BRIEF 和上面一样,改成YES 默认是NO,目的和上面一样
INPUT 源project的目录或者文件名,例如"./lib/" 可以不写,表示当前的目录
FILE_PATTERNS 选择如.c/.h/.cpp等的文件 没有被选择的,如.py会被过滤掉,即最后不会翻译.py的文件
RECURSIVE 递归遍历当前目录的子目录,寻找被文档化的程序源文件 默认是 NO,修改成 YES
HAVE_DOT 改写成YES 生成类图等,前提是需要安装了这个组件

  其他的,个人觉得不太重要,至于其他的可以参看注释,生成文件的每项注释已经非常清楚了。

3. 写注释

  这一块不想说太多了,因为已经有很多人都做了讨论,对自己选好的几种注释方式,进行研究一下即可。(可以参考http://www.cnblogs.com/wishma/archive/2008/07/24/1250339.html)

  需要说明一点的是,我们在写注释的时候,也要注意使用关键字,我目前为止使用到了@file (为整个文件生成对应的页面,如 .h 文件,则可以生成与 .h 文件对应包含所有函数的整体性文件)@fn (声明函数,可以还有 @par, @return等等其他描述函数的参数)、@brief (简要描述)等等。在生成的时候注释中的换行往往会被忽略掉,可以使用\n来产生空行。

4. 运行:

doxygen filename(配置文件名)

三、链接网站:

  1. doxygen的官方网站:http://www.doxygen.nl/index.html
  2. doxygen手册的翻译网站:http://cpp.ezbty.org/book

  现在国内doxygen的使用应该是呈现了逐渐增多的态势,所以关于doxygen方面的博客等有很多很多,虽然大致相同,但是总会有些亮点。具体可以google一下。下面是我现在在学习中的一些问题和心得:

doxygen -g filename

  上面是doxygen初始配置文件的生成命令,其实你可以试一下,无论你在哪个目录下,或者以哪个文件名命名这个初始的配置文件,最后得到的文件内容都是一样的,不会因为你放在哪个目录下或文件名不同而内容有所不同。这也就说明了一个问题,在使用doxygen时,对配置文件所处的位置是没有限制的,而关键的问题是对配置文件进行的修改以及设置(input和output path可以对目标文件以及输出的目录进行设置)。

  如果在上面命令中缺省filename,最后得到的默认文件Docxyfile,其内容和其他生成的文件内容也是一样的。

  在使用的过程中,因为我的粗心,也出现了一个问题。这里指出来,提醒我自己。

  配置文件中有“INPUT PATTERNS =”这个设置项,主要作用是如果你之前INPUT了一个目录而不是一个文件的情况下,过滤性的对源码生成文档。例如:

INPUT PATTERNS = *.cc *.h *.cpp

  上面表示的就是只针对目录下所有的.cc、.h和.cpp源文件生成文档,其他后缀的文件都会被忽略,而我最开始接触这个东西的时候,在网上搜到的大部分设置都是这样的:

INPUT PATTERNS = *.cc \
                 *.h \
                 *.cpp

  我知道“\”是一个换行符号,但是我在使用的时候没有注意到“*.cc”和其之间要有空格,所以这样一来始终都生成不了对应的文档。问题的本质应该在于,doxygen在运行的时候,是根据空格来区分多个参数的,如果不加空格,可能直接被识为了后缀为.cc*.h*.cpp的文件,而目录下是没有这样的文件的,所以会出错。

Avatar_small
OO~ 说:
2013年5月15日 22:21

对doxygen还只是一个初步的认识,虽然说已经在最近用其生成了一个文档,但是感觉自己还是掌握的不好!如果有谁也在用或者即将用到的,希望能和大家交流交流心得!


登录 *


loading captcha image...
(输入验证码)
or Ctrl+Enter