windows下vim和Doxygen自动生成代码文档
本文转自：http://blog.ixpub.net/597712/viewspace-423724
1. 下载DoxygenToolkit 下载地址：http://www.vim.org/scripts/script.php?script_id=987
2. 把DoxygenToolkit.vim放入../Vim/vim72/plugin
3. 修改_vimrc的配置,我的配置是
let g:DoxygenToolkit_paramTag_pre="@param "
let g:DoxygenToolkit_returnTag="@returns "
let g:DoxygenToolkit_blockHeader="--------------------------------------------------------------------------"
let g:DoxygenToolkit_blockFooter="----------------------------------------------------------------------------"
let g:DoxygenToolkit_authorName="Leon Lee"
4. 使用命令
DoxAuthor:将文件名，作者，时间等关键字自动填好
DoxLic:license注释
Dox：函数及类注释
5、使用Doxygen的一般步骤
a) 下载 Doxygen软件(本人Cygwin自带该软件)
b) 下载 Graphviz
c) 安装 Doxygen 和 Graphviz（可选）
d) 准备一个配置文件（Doxyfile）
e) 按照Doxygen规则给源代码添加注释，将代码文档化
f) 运行Doxygen 产生和源代码对应的文档。
6. 生成Doxyfile方法
运行doxygen -g
编辑配置文件
以下文字摘录于http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/index.html
配置文件采用 <TAGNAME> = <VALUE> 这样的结构，与 Make 文件格式相似。下面是最重要的标记：
<OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。<INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的C/C++源代码文件和头文件。例如，请考虑以下代码片段：INPUT = /home/user1/project/kernel /home/user1/project/memory
在这里，doxygen 会从这两个目录读取
C/C++源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把<RECURSIVE>标记设置为 Yes。<FILE_PATTERNS>：在默认情况下，doxygen 会搜索具有典型C/C++扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果<FILE_PATTERNS>标记没有相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为C文件扩展名，就应该在<FILE_PATTERNS>标记中添加这个扩展名。<RECURSIVE>：如果源代码层次结构是嵌套的，而且需要为所有层次上的C/C++文件生成文档，就把这个标记设置为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为 Yes，doxygen 就会递归地搜索整个层次结构并提取信息。<EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为 Yes。<EXTRACT_PRIVATE>：把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。<EXTRACT_STATIC>：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。
清单 3 给出一个 Doxyfile 示例。
清单 3. 包含用户提供的标记值的 doxyfile 示例
OUTPUT_DIRECTORY = /home/user1/docs EXTRACT_ALL = yes EXTRACT_PRIVATE = yes EXTRACT_STATIC = yes INPUT = /home/user1/project/kernel #Do not add anything here unless you need to. Doxygen already covers all #common formats like .c/.cc/.cxx/.c++/.cpp/.inl/.h/.hpp FILE_PATTERNS = RECURSIVE = yes |
运行 doxygen
在 shell 提示下输入 doxygen Doxyfile（或者已为配置文件选择的其他文件名）运行 doxygen。在最终生成 Hypertext Markup Language（HTML）和 Latex 格式（默认）的文档之前，doxygen 会显示几个消息。在生成文档期间，在 <OUTPUT_DIRECTORY> 标记指定的文件夹中，会创建两个子文件夹 html 和 latex。清单 4 是一个 doxygen 运行日志示例。
清单 4. doxygen 的日志输出
Searching for include files... Searching for example files... Searching for images... Searching for dot files... Searching for files to exclude Reading input files... Reading and parsing tag files Preprocessing /home/user1/project/kernel/kernel.h … Read 12489207 bytes Parsing input... Parsing file /project/user1/project/kernel/epico.cxx … Freeing input... Building group list... .. Generating docs for compound MemoryManager::ProcessSpec … Generating docs for namespace std Generating group index... Generating example index... Generating file member index... Generating namespace member index... Generating page index... Generating graph info page... Generating search index... Generating style. sheet... |
文档输出格式
除了 HTML 之外，doxygen 还可以生成几种输出格式的文档。可以让 doxygen 生成以下格式的文档：
- UNIX 手册页：把
<GENERATE_MAN>标记设置为 Yes。在默认情况下，会在<OUTPUT_DIRECTORY>指定的目录中创建 man 子文件夹，生成的文档放在这个文件夹中。必须把这个文件夹添加到 MANPATH 环境变量中。 - Rich Text Format（RTF）：把
<GENERATE_RTF>标记设置为 Yes。把<RTF_OUTPUT>标记设置为希望放置 .rtf 文件的目录；在默认情况下，文档放在 OUTPUT_DIRECTORY 中的 rtf 子文件夹中。要想支持跨文档浏览，应该把<RTF_HYPERLINKS>标记设置为 Yes。如果设置这个标记，生成的 .rtf 文件会包含跨文档链接。 - Latex：在默认情况下，doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中，
<GENERATE_LATEX>标记设置为 Yes。另外，<LATEX_OUTPUT>标记设置为 Latex，这意味着会在 OUTPUT_DIRECTORY 中创建 latex 子文件夹并在其中生成 Latex 文件。 - Microsoft® Compiled HTML Help（CHM）格式：把
<GENERATE_HTMLHELP>标记设置为 Yes。因为在 UNIX 平台上不支持这种格式，doxygen 只在保存 HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。 - Extensible Markup Language（XML）格式：把
<GENERATE_XML>标记设置为 Yes。（注意，doxygen 开发团队还在开发 XML 输出）。
清单 5 提供的 Doxyfile 示例让 doxygen 生成所有格式的文档。
清单 5. 生成多种格式的文档的 Doxyfile
#for HTML GENERATE_HTML = YES HTML_FILE_EXTENSION = .htm #for CHM files GENERATE_HTMLHELP = YES #for Latex output GENERATE_LATEX = YES LATEX_OUTPUT = latex #for RTF GENERATE_RTF = YES RTF_OUTPUT = rtf RTF_HYPERLINKS = YES #for MAN pages GENERATE_MAN = YES MAN_OUTPUT = man #for XML GENERATE_XML = YES |
=====================================分割线=============================
以下是另一篇相关使用方法的转载:
在Linux下面开发，在代码中一般注释doxygen格式的注释，这是帮助我们生成文档的一个好方法。
对于doxygen的主要是语法，网上有很多的说明，有个工程：GNOME Power Manager里面的doxygen
注释写的非常好，你们可以下载下来看看，并且可以借鉴到自己的实际开发中。
这里我想说的是：如何从source code 总提取开源软件的文档。
有3个工具可以先安装一下：
1 doxygen
2 Graphviz
3 htmlhelp
1 doxygen是大名鼎鼎代码文档工具。
下载地址：www.doxygen.org
安装它。
2 Graphviz
这个工具配合doxygen使用，可以提取函数，模块之间的调用关系，非常清晰。
下载地址：http://www.graphviz.org/Download..php
下面是Graphviz提取出来的一些关系图：
 |
 |
 |
|
| cluster | crazy | datastruct | fsm |
 |
 |
 |
|
| hello | profile | sdh | switch |
 |
|||
| unix | world | twopi2 | ER |
 |
 |
 |
 |
| fdpclust | process | softmaint | transparency |
3 htmlhelp
这个工具把doxygen生成的html文件，转化为一个CHM文件，看起来方便些。
下载地址：http://www.softpedia.com/get/Authoring-tools/Help-e-book-creators/HTML-Help-Workshop.shtml
安装它。
4 我们以GNOME POWER Manager为例，看看如何使用这些工具，提供我们的文档能力。
源码下载地址：
http://www.gnome.org/projects/gnome-power-manager/
下载源码，解压后，我们来看看如果使用上面的3个工具：
首先用doxygen: