Linux下使用doxygen+vim生成c语言源程序文档的方法

1.安装 doxygen

有两种获得 doxygen 的方法。可以下载预编译的可执行文件，也可以从 SVN 存储库下载源代码并自己编译。清单 1 演示的是后一种方法。

清单 1. 安装和构建 doxygen 源代码

bash-2.05$  git clone https://github.com/doxygen/doxygen.git

bash-2.05$ cd doxygen

bash-2.05$ ./configure

bash-2.05$ make

bash-2.05$ make install

2.安装graphviz 软件包

 yum list available 'graphviz*'
        yum install 'graphviz*'

3.使用 doxygen 生成文档

使用 doxygen 生成源代码的文档步骤:

清单 2. 生成默认的配置文件

bash-2.05b$ doxygen -g

这个命令在当前目录中生成一个可编辑的配置文件Doxyfile。可以改变这个文件名，在这种情况下，应该调用 doxygen -g <user-specified file name>

编辑配置文件

配置文件采用 <TAGNAME> = <VALUE> 这样的结构，与 Make 文件格式相似。下面是最重要的标记：

# 项目名称，将作为于所生成的程序文档首页标题

PROJECT_NAME        = “Test”

# 文档版本号，可对应于项目版本号，譬如 svn、cvs 所生成的项目版本号

PROJECT_NUMBER      = "1.0.0”

# 这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。

OUTPUT_DIRECTORY    =  doc/

# 程序文档语言环境

OUTPUT_LANGUAGE     = Chinese

# 如果是制作 C 程序文档，该选项必须设为 YES，否则默认生成 C++ 文档格式

OPTIMIZE_OUTPUT_FOR_C  = YES

# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化

TYPEDEF_HIDES_STRUCT   = YES

# 在 C++ 程序文档中，该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字空间这样的概念，所以此处设置为 YES

HIDE_SCOPE_NAMES       = YES

# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息

QUIET   = YES

# 在默认情况下，doxygen 会搜索具有典型 C/C++ 扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果 <FILE_PATTERNS> 标记没有相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为 C 文件扩展名，就应该在 <FILE_PATTERNS> 标记中添加这个扩展名。为空即可

FILE_PATTERNS          =

# 递归遍历当前目录的子目录，寻找被文档化的程序源文件

RECURSIVE              = YES

# 示例程序目录，填文件路径

EXAMPLE_PATH           = example/

# 示例程序的头文档 (.h 文件) 与实现文档 (.c 文件) 都作为程序文档化对象,为空

EXAMPLE_PATTERNS       =

# 递归遍历示例程序目录的子目录，寻找被文档化的程序源文件

EXAMPLE_RECURSIVE      = YES

#这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为 Yes。

EXTRACT_ALL = yes

#把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。

EXTRACT_PRIVATE = yes

#把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。

EXTRACT_STATIC = yes

#在这里，doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把 <RECURSIVE> 标记设置为 Yes。

INPUT = /home/user1/project/kernel  /home/user1/project/memory

# 允许程序文档中显示本文档化的函数相互调用关系

REFERENCED_BY_RELATION = YES

REFERENCES_RELATION    = YES

REFERENCES_LINK_SOURCE = YES

# 在程序文档中允许以图例形式显示函数调用关系，前提是你已经安装了 graphviz 软件包

UML_LOOK = YES

HAVE_DOT              = YES

CALL_GRAPH            = YES

CALLER_GRAPH          = YES

#让doxygen从配置文件所在的文件夹开始，递归地搜索所有的子目录及源文件

RECURSIVE = YES 

#在最后生成的文档中，把所有的源代码包含在其中

SOURCE BROWSER = YES

$这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系

GENERATE TREEVIEW ＝ ALL

 

4.运行 doxygen

在 shell 提示下输入 doxygen Doxyfile（或者已为配置文件选择的其他文件名）运行 doxygen。在最终生成 Hypertext Markup Language（HTML）和 Latex 格式（默认）的文档

5.安装下载 doxygen的 vim 插件

 http://www.vim.org/scripts/script.php?script_id=987

将下载的插件安装到$VIMRUNTIME/plugin目录下，例如(vim的版本为7.2)：

# cp DoxygenToolkit.vim /usr/share/vim/vim72/plugin/

之后，需要在VIM的配置文件中(/etc/vimrc)为doxygentoolkit这个插件配置一些全局变量：

let g:doxygenToolkit_authorName="your name"

let g:doxygenToolkit_briefTag_funcName="yes"

（在DoxygenToolkit.vim中举了一一些例子如何在.vimrc中添加配置）

这样，你就可以通过在vim中输入：DoxAuthor，Dox，Doxb等几个命令来完成doxygen风格的文档了。当然，你可以用VIM的map功能来绑定这几个命令。我通常采用以下绑定：

map <F3>a :DoxAuthor

map <F3>f :Dox

map <F3>b :DoxBlock

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

6.添加Doxygen的注释
命令 :Dox    
    在添加注释时，最常用的是:Dox，而每个文件同时也需要:DoxAuthor来添加文件头。

使用:Dox命令来为一个函数添加注释十分简单：

• 把光标移动到函数声明或者定义所在行(函数原型所在行)，
• 执行:Dox。
• Doxygen会自动解析你的函数原型，并将相应的参数和返回值列出来。

例如，当你对int invoke(int
a, int b, int operation=0)添加注释时，Dox将生成如下代码

/**

* @brief invoke

*

* @param a

* @param b

* @param operation

*

* @return

*/

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

命令 :DoxAuthor

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

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