windows下vim和Doxygen自动生成代码文档
2012-08-01 21:07
555 查看
本文转自: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
配置文件采用
在这里,doxygen 会从这两个目录读取
.c、.cc、.cpp、.h 和 .hpp。如果
.c86 作为
Yes。例如,请考虑源代码根目录层次结构 /home/user1/project/kernel,其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为
Yes,doxygen 就会递归地搜索整个层次结构并提取信息。
Yes。
清单 3 给出一个 Doxyfile 示例。
清单 3. 包含用户提供的标记值的 doxyfile 示例
运行 doxygen
在 shell 提示下输入
清单 4. doxygen 的日志输出
文档输出格式
除了 HTML 之外,doxygen 还可以生成几种输出格式的文档。可以让 doxygen 生成以下格式的文档:
UNIX 手册页:把
Rich Text Format(RTF):把
Yes。把
rtf 子文件夹中。要想支持跨文档浏览,应该把
Latex:在默认情况下,doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中,
Yes。另外,
latex 子文件夹并在其中生成 Latex 文件。
Microsoft® Compiled HTML Help(CHM)格式:把
Yes。因为在 UNIX 平台上不支持这种格式,doxygen 只在保存 HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。
Extensible Markup Language(XML)格式:把
Yes。(注意,doxygen 开发团队还在开发 XML 输出)。
清单 5 提供的 Doxyfile 示例让 doxygen 生成所有格式的文档。
清单 5. 生成多种格式的文档的 Doxyfile
=====================================分割线=============================
以下是另一篇相关使用方法的转载:
在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提取出来的一些关系图:
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:
生成的帮助文档里面带有,call graph.
接着用htmlhelp workshop:
生成的CHM文件:
以及各个调用关系,一目了然:
从生成的代码注释上看,GNOME Power Manager对于注释用的是非常好的,这可以用到我们的实际开发中。
另外GNOME Power Manager是对GObject用的最好的,大家也可以借鉴其用法。
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 |
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/docsEXTRACT_ALL = yesEXTRACT_PRIVATE = yesEXTRACT_STATIC = yesINPUT = /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/.hppFILE_PATTERNS = RECURSIVE = yes |
在 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 excludeReading input files...Reading and parsing tag filesPreprocessing /home/user1/project/kernel/kernel.h…Read 12489207 bytesParsing input...Parsing file /project/user1/project/kernel/epico.cxx…Freeing input...Building group list.....Generating docs for compound MemoryManager::ProcessSpec…Generating docs for namespace stdGenerating 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 = YESHTML_FILE_EXTENSION = .htm#for CHM filesGENERATE_HTMLHELP = YES#for Latex outputGENERATE_LATEX = YESLATEX_OUTPUT = latex#for RTFGENERATE_RTF = YESRTF_OUTPUT = rtf RTF_HYPERLINKS = YES#for MAN pagesGENERATE_MAN = YESMAN_OUTPUT = man#for XMLGENERATE_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 |
这个工具把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:
生成的帮助文档里面带有,call graph.
接着用htmlhelp workshop:
生成的CHM文件:
以及各个调用关系,一目了然:
从生成的代码注释上看,GNOME Power Manager对于注释用的是非常好的,这可以用到我们的实际开发中。
另外GNOME Power Manager是对GObject用的最好的,大家也可以借鉴其用法。
相关文章推荐
- windows下vim和Doxygen自动生成代码文档
- windows下vim和Doxygen自动生成代码文档
- doxygen + vim 自动生成C文档教程
- 【转】windows环境下利用doxygen生成代码文档
- 使用Doxygen软件将程序代码自动生成chm格式帮助文档
- windows下doxygen 生成代码文档
- linux c/c++ 代码使用 doxygen 自动生成文档
- 使用JSDoc自动生成代码文档
- vs2010代码注释自动生成api文档(Sandcastle帮助文档生成器使用介绍)
- 用doxygen为C/C++程序自动生成文档(二)-doxygen风格注释简介
- (VC++6.0 )基于单文档对话框的自动生成代码注释
- Ruby on rails开发从头来(windows)(十八)-自动生成文档
- 用doxygen+graphviz自动化生成代码文档(附详细教程)
- Doxygen自动文档生成工具在Eclipse中的集成及使用举例
- jsdoc-toolkit--让JavaScript代码自动生成API文档
- 使用Doxygen来自动化生成项目代码文档
- doxygen windows下实战生成chm文档
- [Dynamic Language] 用Sphinx自动生成python代码注释文档
- 用doxygen+graphviz自动化生成代码文档(附详细教程)
- PHP 自动生成帮助文档工具1.0Beta版【代码维护神器】