Linux下doxygen的使用 | 迟思堂工作室
当前位置: 首页 > GNU/Linux系统 > 正文

Linux下doxygen的使用

doxygen是一种从源代码生成文档的工具,支持多种语言。当然,源代码中需按一定的格式写注释,这些注释的格式也能帮助我们养成很好的注释习惯,可以尝试一下。

使用doxygen生成文档的方法很简单:

$ doxygen -g –s

$ doxygen

只需两个简单命令就可以了。

下面简单说明一下:

1、在工程目录下输入doxygen –s –g doxyconfig,其中doxyconfig为生成配置的文件名称,可任意指定,如果不指定,默认生成的配置文件为Doxyfileman手册中没有详细说明选项的意思,这里不妨猜测一下,-ssimple-ggenerate,如果不指定-s,则生成的配置文件大约为63KB,行数约1500左右;反之,则约成10KB,行数约250左右。——此处猜测便根据这些测试而来的。

2、生成配置文件后,会出现提示信息,大意是说那个配置文件已经生成了,现在编辑它,之后输入doxygen Doxyfile(经实践证明,可以只输入doxygen命令)就可以产生工程的文档了。如果再次使用doxygen生产配置文件,则原来的就配置文件就变成了备份文件,添加后缀名.bak

3、根据doxygen要求的注释格式来编写代码的注释,这一步要求比较高,而且工作量比较大。我们在文章后面还要讲解的。

下面介绍一下如何编辑生成的配置文件,我们以我们的串口程序为例子。

 

doxygen的配置文件与大多数linux平台的配置文件类似,就是一些关键字与值,配置文件中的值以YESNO居多。

DOXYFILE_ENCODING = UTF-8,默认编码为UTF-8,这样可以支持中文。

PROJECT_NAME = “SerialPort”,项目名称,多个单词需要使用引号(“”)。

PROJECT_NUMBER = “1.0 beta”,项目版本号。

OUTPUT_DIRECTORY = serialport-html,输出文档的目录,如果为空,表示在当前目录,建议写上表示本工程的有意义的目录名称,比如我们就指定目录名称为serialport-html。

OUTPUT_LANGUAGE = English,文档语言,可以指定为Chinese。

IMAGE_PATH = image_dir,指定图片存放的目录,我们将图片放到当前目录下的image_dir目录中,因为我们的文档会出现测试图片示例。

HTML_OUTPUT= . ,html输出目录名称,默认为html目录,如果为“.”则表明为上述OUTPUT_DIRECTORY目录。

GENERATE_LATEX = NO,是否生成LaTeX,默认生成的,但我们不想生成。

好了,我们需要修改的就这么多,使用上述第2步骤的命令就可以生成一个漂亮的文档了。此外还有一些常用的设置选项。

INPUT =xxx,代码文件或目录,多个文件(目录)需要以空格隔开,如果不指定,表示当前目录,但是,如果指定目录且当前目录有代码文件的话,需要使用点号(“.”)表示当前目录。

FILE_PATTERNS=xxx,指定各种文件,我们常用为*.cpp *.c *.h,等等。

上面基本就是我们常用的了,如果还想更深入了解,请移步到google网站。

下面就是真正需要花费一定时间的工作:为我们的程序作特定格式的注释。

doxygen支持多种注释风格,比如JavaDoc风格,它在C语言块注释开始处再添加一个星号(*)构成,如下:

1.           /**

2.            * … text …

3.            */

Qt风格:

	1.           /*!
	2.            * ... text ...
	3.            */

上面两种方式中间的星号(*)是可选的,不过,个人认为添加会更美观一些。

C++风格的,——就是在C++注释后面再添加“/”:

	1.           ///
	2.           /// ... text ...
	3.           ///

或者是这样:

	1.           //!
	2.           //!... text ...
	3.           //!

经测试,实际使用中,如果是单行注释的话,可以使用如下的格式:

	1.           /** ... text ... */
	2.           /**< ... text ... */

这些格式会被doxygen文档化,如果不想让它文档化,可以“破坏”这些格式,比如可以使用“正宗”的C/C++注释:

	1.           /* ... text ... */
	2.           // ... text ...

上述风格来自doxygenmanual页面,具体地址为:

 

下面介绍一下常用doxygen的命令,更多详细使用说明,请参考如下地址:

doxygen命令以@开始,两种方式均可以。文中以@标记之。

@def 宏定义说明

@fn 函数 函数说明

@param 参数 参数说明

@return 返回值说明(出错返回什么值,等等)

@file 文件名

@author 作者

@version 程序版本

@date 日期

@note 注解(注意事项,等)

@warning 警告信息

@bug bug信息

@test 测试示例、信息

@todo 一些未完事宜

(@bug、@test以及@todo等会出现链接页面)

上面这样适合在函数、文件前面出现。

下面为生成特殊字体的命令:

@a @e @em:其后的单个字(word)表现为斜体,以强调作用。如有多个word的话,使用<em>xxx xxx</em>代替。

@b:其后的word为粗体,多个则使用<b>xxx xxx</b>。

@c @p:字体表现为打印机字体,多个则使用<tt>xxx xxx</tt>。

 

下面是一些具体的实例。 

在文件开始处的版权声明及其它信息:

/**

*                      Copyleft (C) 2010  Late Lee

*        This program is tested on LINUX PLATFORM, WITH GCC 4.x.

*        The program is distributed in the hope that it will be

*        useful, but WITHOUT ANY WARRANTY. Please feel free to

*        use the program, and I feel free to ignore the related

*        issues. Any questions or suggestions, or bugs, please

*        contact me at  or e-mail to

*         if you want to do this.

* @file   serialport.c

* @author Late Lee

* @date   Mon Jan 10 2011

*

* @brief  Some utils of the serial port, such as open the port, close

*         the port and setup the port.

* @note   This is a note.

* @warning This is a warning.

* @bug    This is a bug.

*/

 

在函数前的注释:

 

/**

* open_port – Open a serial port

*

* @param port : The port number, eg, open_port(1) will open com1

*

* @return Return fd if success, otherwise will return -1 with some msg.

*/

定义宏使用的注释:

/**

* @def error_exit

* @brief A macro that prints the @a error msg and exit.

*/

#define error_exit(error)

do{

fprintf(stderr, “%sn”, error);

exit(0);

while(0)

 

 

或者你会说,这样的注释风格太麻烦了!不怕!现在有了跟emacs结合的doxymacs,在emacs中配置了doxymacs,这些注释是十分方便的!比如需要在文件前插入注释,按C-c d i即可,在函数前插入注释,按C-c d f即可,等等。具体的请移步到这里的文章:/embedded-linux/learning-elinux-4-my-emacs-ii/embedded-linux/learning-elinux-4-my-emacs如果你使用的不是emacs,那Sorry,我也不太会,如果你懂,不妨分享一下。

这个串口程序的文档已经放到网站上了,这里main.c文件参考页面地址:/yetanothertest/serialport-html-cn/main_8c.html

此外,我们还测试生成中文文档,因此doxygen使用UTF8,因此只要将代码文件保存为utf8编码即可(使用Ultra Editnotepad++等等编辑器很容易做到)。但这又引出一个问题,gcc并不支持utf8!经过google,发现gcc 4.4.0版本以后已经支持utf8了,因此,为了做这个测试,花了一个小时左右编译、安装高版本的gcc(我们使用4.4.5版本),结果,这个版本的gcc是支持utf8的。后来,又发现,如果使用“UTF-8 BOM格式编码”格式保存源文件的话,在原来的gcc下也编译通过。因此如果想在程序中使用中文注释,建议以此格式保存,当然,在系统的locale不是中文的情况下看到的中文是乱码的。

1、尽信书则不如无书,我们建议各位到实践中试一试,这样学到的知识才是我们自己的,比如,在指定源代码目录中,我的测试文件main.c放在当前目录下,如果不指定“.”的话,doxygen便不会处理该文件,这是网上很多资料没有说明的,因此需要实践才能了解。

2、我们强烈建议各位到官方网站学习,因为其它地方绝大部分都出自官方网站,manual页面地址是:

近来经济拮据,如本文对阁下有帮助,可慷慨解囊赞助笔者以输出更多好文章。
支付宝[email protected] 或 微信fly_camel_fly 均可。感谢!
14373903313201                                  14373903313202

本文固定链接: /using-gnu-linux/how-to-use-doxygen-under-linux.html

如无特别说明,迟思堂工作室文章均为原创,转载请注明: Linux下doxygen的使用 | 迟思堂工作室

目前暂无评论

发表评论

*

快捷键:Ctrl+Enter