使用getopt()进行命令行处理
终于把APUE看完一遍

doxygen+VIM文档实用指南for C/C-liked Programmers

simplyzhao posted @ 2009年5月02日 08:56 in Unix-C Programming with tags doxygen vim doxygentoolkit , 4332 阅读

好文啊, 忍不住就又拷贝过来了呵呵

来源: blog.csdn.net/clarkZHUO/archive/2006/12/31/1471573.aspx

再次感谢原文作者,

 

摘要:

文档撰写是一项十分繁琐而且费力的工作,相信已经有很多人对此深感头痛。文档生成工具的出现最大限度地帮助程序员解决了这个问题,这些工具通常可以从程序源代码自动生成文档,大大方便了文档工作。这篇小东西主要介绍了如何用VIMdoxygen来快速生成注释,并用最少的额外劳动来完成专业水准的程序文档的过程。仅供参考,如有雷同,纯属巧合。 

关键字:

       doxygen vim doxygentoolkit chm dot lex CLanuageScanner


补充:

本文一开始是为dylan同学准备的,后来有所扩展。本文不涉及doxygen注释的具体做法,因为可以在网上得到更多关于这方面的范例和资料。

 

什么是doxygen

doxygen是一个十分好用的自由软件,是一种文档生成器,其工作机制是利用注释中的有效信息来自动生成文档。目前doxygen的最新版是(1.5.1),从http://www.doxygen.org上可以下载最新版的doxygen1.5.1版的doxygen可处理的语言包括:

l         C/C++

l         Java

l         Python

l         PHP

l         Objective-C

l         IDL (Corba, MicrosoftKDE-DCOP类型)

l         C#

l         D

它支持以下文档格式:

l         HTML

l         XML

l         LaTeX

l         RTF

l         Unix Man Page

         有了doxygen的支持后,从软件代码到项目文档的转化十分简单,直接执行doxygen可执行程序就可以了。此时doxygen会在当前目录下寻找默认的配置文Doxyfile(此文件可以手工编写,也可以借助于doxywizard生成),并从配置文件中读入待解析的文件列表和一些设置,最后生成相应格式的文档。而你所需要做的唯一工作,就是在软件代码中添加doxygen能够识别的注释。也就是说,只要在编辑代码的时候遵从doxygen的规范来添加注释,就毫不费劲地生成程序文档了。

和其他的一些注释工具相比,doxygen的优势在于它支持众多的文件类型,并能够生成十分漂亮的网页。一个典型的doxygen文档包含文件列表,函数列表,全局变量列表,结构体列表,为读者提供全局的信息。doxygen的自带的tag工具还可以帮助生成交叉索引,方便从一个函数跳转到另一个函数。这对于了解整个项目的结构和接口以及调用关系是十分有益的。

多说无益,下面给一个简单的范例,看看doxygen是如何工作的。(此部分代码也是用doxygen生成的)

 

00001 /**

00002  * @file show.c

00003  * @brief written to show the doxygen documentation tool.

00004  * @author Clark ZHUO, zkk@mails.tsinghua.edu.cn

00005  * @date 2006-11-09

00006  */


00007 #include <stdio.h>

00008

00009 extern void printf(const char *format, ...);

00010 extern void fprintf(FILE f, const char *format, ...);

00011

00012 /**

00013  * @mainpage

00014  * The page is showed to you!

00015  *

00016  * @defgroup macro

00017  * @addtogroup macro

00018  * simple macro

00019  * @{ */


00020 /** it is a macro

00021  * the doxygen merge the message*/


00022 #define MACRO1 1

00023 /** @} */

00024

00025 /** @defgroup codes

00026  * @addtogroup codes

00027  * codes of this function

00028  * @{*/


00029

00030 const char[] msg="Hello, doxygen!";     

00031 /**

00032  * @brief @b invoke just invoke some example

00033  *

00034  * @param a first parameter

00035  * @param b second paremeter

00036  * @param operation selectable paremeter

00037  *

00038  * @return

00039  *      - MACRO1 if default operation is called

00040  *      - 0 if a or b is 0

00041  *      - -1 else

00042  */


00043 int invoke(int a, int b, int operation=0)

00044 {

00045         printf(msg);

00046         if (operation != 0) {

00047                 fprintf(2, "just a test.");

00048                 return MACRO1;

00049         }

00050         if ( (a==0) || (b==0)) return 0;

00051         return -1;

00052 }

00053

00054 /**

00055  * @brief main the function for the program

00056  *

00057  * @param argc argument count for std C main

00058  * @param argv argument value for std C main

00059  *

00060  * @return always return 0 to shell

00061  */


00062 int main(int argc, char *argv[])

00063 {

00064         int val=1;

00065         int valb=2;

00066

00067         printf("Program starts...\n");

00068         /** <b> In function: </b> the main function called invoke*/

00069         invoke(val, valb);

00070         return 0;

00071 }

00072

00073 /** @}*/

 

说明:以上例子主要演示了file, function, param, return等常用的doxygen标签,在doxygen帮助的Special Commands”部分列出了所有的标签。

        可以注意到,代码中所有的注释都以/**开头,这正是doxygen的一个标记,说明这段注释文本将被doxygen进行解释。事实上,doxygen同时支持好几种类型的注释风格,包括JavaDoc风格的/** */QT风格的/*! */,和行注释风格的/////!

        还可以注意到注释中有很多以@为前缀的语句,这些紧跟在@符号后面的标识符就是doxygen的关键字(也可以用’\\’来替代’@’)。doxygen通过这些关键字来组织所生成的文档。例如,@file告诉doxygen后面的字符串是文件的名字,而@date则说明了文件的生成时间。

        以下就是所生成的文档中函数列表中关于invoke的部分,效果还不错吧^_^(左侧是index页的模块列表,右侧是函数invoke的文档)

 

什么是VIM

         这个问题就直接跳过了。作为最有名的编辑器之一,网上有铺天盖地的文章来介绍VIM的各种技巧。www.vim.org上面也有足够的信息和资源。你只用IDE?那你往下看看用VIM能不能给你带来更高的效率,如果值得,不妨只用IDE来编译和调试。

为什么要使用doxygen+VIM

         从前文已知,doxygen确实是一种很不错的工具。但是为了帮助doxygen来生成文档,你需要在注释上花费更多的时间和精力。通常,这意味着你在写注释的时候需要更集中的注意力,和敲击更多的键盘。如果既想享受doxygen带来的便利,又不愿意在每次写注释的时候多写一大堆相似的,重复性的东西。这时候该怎么办呢?可以使用编辑器插件来最小化自己键入的字符。

         作为世界上最著名的两大编辑器之一,VIM拥有众多的fans。和emacs不同,VIM的迷人之处在于其简约之美和强大的可扩展性。在随后的部分中我将向大家介绍doxygenToolkit.vim这个插件的基本用法。在安装这个插件之后,你只需要执行一个简单的操作,就可以完成doxygen风格的注释。它将使你的编码工作事半功倍。

         doxygentoolkit.vim插件可以在www.vim.org上获取。

需要做什么

以下将简要介绍VIM+doxygen的使用方法:

1)        准备工作

安装doxygen,安装gvim,下载doxygentoolkit.vim并将其安装到$VIMRUNTIME/plugin目录下。

之后,需要在VIM的配置文件中(windows下的_vimrclinux下的vimrc或者~/.vimrc)doxygentoolkit这个插件配置一些全局变量:

let g:doxygenToolkit_authorName="your name"

let g:doxygenToolkit_briefTag_funcName="yes"

其余的配置可以自己查阅doxygentoolkit的说明。这样,你就可以通过DoxAuthorDoxDoxb等几个命令来完成doxygen风格的文档了。当然,你可以用VIMmap功能来绑定这几个命令。我通常采用以下绑定:

map <F3>a :DoxAuthor

map <F3>f :Dox

map <F3>b :DoxBlock

map <F3>c O/** */<Left><Left>

2)        添加注释

        在添加注释时,最常用的是:Dox,而每个文件同时也需要:DoxAuthor来添加文件头。

使用:Dox命令来为一个函数添加注释十分简单。你只需要把光标移动到函数声明或者定义所在行(函数原型所在行),然后执行:Dox就可以了。Dox会自动解析你的函数原型,并将相应的参数和返回值列出来。例如,当你对

int invoke(int a, int b, int operation=0)

添加注释时,Dox将生成如下代码

/**

 * @brief invoke

 *

 * @param a

 * @param b

 * @param operation

 *

 * @return

 */

并将光标设知道invoke后面,方便你输入函数的简单描述。

:DoxAuthor则会自动将文件名,作者,时间等关键字自动填好,十分方便。

当然,你也可以按照自己的配置来修改doxygenToolkit.vim

 

3)        配置并运行doxygen

        doxygen的配置文件是一个文本文件,理论上你可以自己来直接修改。不过还有更省事的方法:doxygen为我们提供了doxywizard图形配置工具。doxywizard的功能十分直观,用起来很简单,在此不加赘述。进行配置之后,将配置文件存到工作目录下,运行doxygen。默认情况下,doxygen会产生html格式的文档,这些文件都会保存在工作目录的html子目录下面。之后,可以通过浏览器来打开html子目录下的index.html页面来查看为这个工程生成的文档。当然,如果你需要生成其他格式的文档,可以进行相应的配置。

doxygen配置文件的细节,我就不一一细述了,你可以去查阅更多的资料J

下图为Windows操作系统下doxygen的图形配置程序doxygenWizard

4)        编译成chm

        使用chm格式的文件来作为程序的文档可以使文档更加便于管理,现在也有越来越多的文档用chm格式发布。doxygen也可以支持编译生成chm格式的文件。这时候,你需要在doxygen的配置文件里设置以下选项(打开chm的支持,并配置htmlworkshop的位置):

GENERATE_HTMLHELP = YES

HHC_LOCATION           = "C:/Program Files/HTML Help Workshop/hhc.exe" (如果hhc已经在系统的路径里,那么此处可以不填)

        这样,doxygen在产生文档的时候会同时产生hhp后缀的文件,并自动运行HHC来帮你编译生成CHM的文件。当然,你也可以在Html Help Workshop里面用hhp文件来手动chm文件了。Html Help Workshop可以在各大软件站点上找到或者去微软的站点上下载:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

5)        一些配置选项

我比较经常进行更改的doxyfile选项有:

INPUT                  = . ../include         项目的路径(用空格隔开,可以用引号括起来)

HIDE_UNDOC_MEMBERS     = NO             是否需要隐藏未注释的成员

SOURCE_BROWSER         = YES             是否显示源程序

GENERATE_HTML          = YES               生成html格式的文档

GENERATE_HTMLHELP      = YES             生成chm文件

CHM_FILE               = show.chm         chm文件的名字

HHC_LOCATION           = "C:/Program Files/HTML Help Workshop/hhc.exe"            hhc的路径

HAVE_DOT                      = YES                      支持图形扩展

……

Dot图形扩展

        doxygen的配置中打开DOT选项后,doxygen可以帮你生成十分眩目的图形支持,使项目文档更加直观、易读。

        为了能够使用Dot图形扩展,你需要首先安装graphviz,这是一个免费的图形库扩展,可以从http://graphviz.org 下载。下载完Dot并安装完毕之后,需要在doxygen文件中将以下选项打开:

HAVE_DOT = YES

进行相关DOT选项的设置之后,就可以生成带图形支持的文档了,这可以让你的文档增色不少。以下是一个函数调用关系图的范例(这是doxygen项目中的一个函数)

doxygen方便扩展吗?

        尽管doxygen已经包含了许多最通用的文件类型的支持,你也许还希望能够让其为你自定义的某种语言生成文档,或者对某个功能进行调整。这时候,你可以添加一些额外的代码,并将源代码重新编译一遍。(当然,你也可以让作者添加对新语言的支持并发布新版本,呵呵)

        doxygen项目的大部分代码是C++文件,大部分的代码解析工作是在*Scanner类里面进行的(目前包含CLanuageScannerPythonLanuageScanner,前者处理所有类C的语言类型,后者是1.5新添加的针对python的类)。这些*Scanner是由lex语法解析器来自动生成的,可以通过修改scanner.lpyscanner.l这两个文件来修改一些细节的处理。这些l文件中大量使用了lexstart condition,使所做修改不会轻易破坏已有的功能,比较方便。如果你所要添加的这种语言是类C结构的,也许只需要把这个文件类型添加到已有的C语言框架里就可以让一切正常工作。

        修改完毕之后,将整个项目重新编译一遍,make程序将自动更新*Scanner类的内容,并将你所做的修改应用到doxygen程序上。调试之,就大功告成了。

小结

         doxygen+VIM+doxygenToolkit.vim+Html Help Workshop = 注释->简单的文档解决方案

         doxygen还有众多十分有用的关键字和其它的功能,有兴趣的朋友可以好好去发掘发掘。doxygen的主页上也有很多很有用的讨论,值得去好好看看。

         lex感兴趣的朋友可以去看看doxygenscanner.l文件,肯定会有比较大的收获。

 

Enjoy Linux, Fighting.
Avatar_small
capella login 说:
2022年8月20日 03:59

Log in with your Capella University User ID to continue your application or check your application status. capella login All fields required, unless marked optional. User ID. Log in to Capella. Review your saved programs, connect with your enrollment counselor, and track your progress. Log In. capella university login Forgot your username


登录 *


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