doxygen系列问题
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(配置文件名)
三、链接网站:
- doxygen的官方网站:http://www.doxygen.nl/index.html
- 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的文件,而目录下是没有这样的文件的,所以会出错。
2013年5月15日 22:21
对doxygen还只是一个初步的认识,虽然说已经在最近用其生成了一个文档,但是感觉自己还是掌握的不好!如果有谁也在用或者即将用到的,希望能和大家交流交流心得!
2024年1月10日 13:55
JNANABHUMI AP provides all latest educational updates and many more. The main concept or our aim behind this website has been the will to provide resources full information on each topic which can be accessed through Internet. To ensure that every readers get’s what important and worthy about the topic they search and link to hear from us. jnanabhumiap.in Jnanabhumi AP is a startup by passionate webmasters and bloggers who have passion to provide engaging content which is accurate, interesting and worthy to read. We are mope like a web community where you can find different information’s, resources, topics on day to day incidents or news. We provide you the finest of web content on each and every topics possible with help of editorial and content team.