使用doxygen为C/C++程序生成中文文档
文章来自:http://www.fmddlmyy.cn/text21.html
依照约定的格式凝视源码,用工具处理凝视过的源码产生文档。通过这样的方式产生文档至少有下面优点:
- 便于代码和文档保持同步。
- 能够对文档做版本号管理。
非常多编程语言都有类似的文档工具,比如:Java有javadoc,Ruby有rdoc。对于C/C++程序,我们能够用Doxygen生成文档。本文通过为一个C++程序“谁养鱼”建立文档,介绍了如何在Windows平台使用Doxygen。
Doxygen比較适合制作API的接口文档,CHM是这类文档的常见格式。
最新版本号的Doxygen(眼下是1.5.2)统一採用UTF-8作为输出文件的编码格式,但微软的CHM编译工具不支持UTF-8。这就为制作中文CHM文档带来麻烦。
本文提出了解决问题的方法。
1 Doxygen简单介绍
1.1 要做什么
使用Doxygen生成文档。主要是两件事:
- 写一个配置文件(Doxyfile)。一般用Doxywizard生成后。再手工改动。
- 依照Doxygen的约定,将代码“文档化”。
然后仅仅要运行命令:
doxygen Doxyfile
就能够了。输入文件、输出文件夹、參数等都是在Doxyfile中配置的。
1.2 得到什么
Doxygen的输出格式主要有HTML、LATEX、RTF等:
- Doxygen在输出HTML文档时,能够自己主动准备用于制作CHM的项目文件(.hhp)、文件夹文件(.hhc)和索引文件(.hhk)。
用HTML Help Workshop中的CHM编译器(hhc.exe)编译后生成CHM文件。
- Doxygen在输出LATEX文档的同一时候准备了转换到pdf格式的makefile。仅仅要系统安装了合适的TEX工具,就能够从LATEX文档生成pdf文档。
- Doxygen输出的RTF格式,已经针对Word作了优化。能够较好地转换到Word文档。
1.3 须要什么
完毕本文的范例须要下面工具:
- Doxygen的最新版本号。能够从Doxygen的站点下载。
- Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形,比如类的继承关系图、合作图,头文件包括关系图等。能够从Graphviz的站点下载Graphviz的最新版本号。Doxygen使用了Graphviz的布局引擎dot,所以在文档中将其称作dot。
- 为解决中文问题。须要使用Cygwin的iconv程序作编码转换。
- 为解决中文问题,须要一个命令行的查找替换工具。
我选择了白杨创作的工具fr。
能够从我的主页http://www.fmddlmyy.cn下载这些工具:Doxygen
1.5.2、Graphviz 2.12、iconv
(GNU libiconv 1.9)和fr 2.1.1.120。
2 CHM格式的中文问题
前面说过:眼下,Doxygen统一採用UTF-8作为输出文件的编码格式。但微软的CHM编译工具(hhc.exe)不支持UTF-8。假设直接用hhc.exe编译,中文不能正确显示。解决问题的思路非常easy:
- 将Doxygen输出的html文件以及CHM的项目文件(.hhp)、文件夹文件(.hhc)和索引文件(.hhk)所有转换到GBK编码后,再用hhc.exe编译就可以。
能够用iconv对文件作编码转换。对于html文件。除了文件内容的编码转换外,还要将
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
中的“UTF-8”替换成“gb2312”。
2.1 用批处理简化操作
我写了一些批处理文件(.bat)用于简化处理过程。包含:
2.1.1 clean.bat —— 清空曾经输出
@echo off
echo 清空曾经输出
if exist refman.chm del /f /q refman.chm
if exist output\html del /f /q output\html\*.*
if exist output\latex del /f /q output\latex\*.*
if exist output\rtf del /f /q output\rtf\*.*
if exist output del /f /q output\*.*
2.1.2 build.bat —— 调用doxygen生成文档
@echo off
echo 生成文档
doxygen Doxyfile
2.1.3 utf82gbk.bat —— 将指定文件(支持通配符)从utf-8编码转换到gbk编码
@echo off
echo 将%1从utf-8编码转换到gbk编码
for %%f in (%1) do copy %%f %%f.utf8
for %%f in (%1) do iconv -c -f utf-8 -t gbk %%f.utf8 > %%f
这个批处理文件要求系统当前路径上有iconv.exe。运行iconv时,使用-c參数忽略无法转换的字符。
否则假设输入文件包括无法转换的字符,转换会失败。
输入文件被备份到加过.utf8后缀的文件。
2.1.4 html-utf82gbk.bat —— 将指定html文件(支持通配符)从utf-8编码转换到gbk编码
@echo off
call utf82gbk %1
echo 将%1中的charset从UTF-8改为gb2312
fr %1 -f:charset=UTF-8 -t:charset=gb2312
这个批处理文件要求系统当前路径上有iconv.exe和白杨的fr.exe。
2.1.5 makechm.bat —— 用Doxygen的输出制作chm文件
@echo off
echo 将Doxygen输出文件编码从utf-8转换到gbk
set path=%path%;%cd%
cd output\html
echo 处理chm输入文件
call utf82gbk.bat index.hhp
call utf82gbk.bat index.hhc
call utf82gbk.bat index.hhk
call html-utf82gbk *.html
echo 生成chm文件
"C:\Program Files\HTML Help Workshop\hhc.exe" index.hhp
if exist index.chm copy index.chm ..\..\refman.chm
del /f /q *.chm
cd ..\..
这个批处理文件如果系统在文件夹“C:\Program Files\HTML Help Workshop\”安装了“HTML Help Workshop”。并如果输出文件夹是Doxyfile所在文件夹的子文件夹output。
2.1.6 rebuild.bat —— 又一次生成chm文件
@echo off
call clean.bat
call build.bat
call makechm.bat
2.2 小结
了解DOS命令的朋友应该非常easy看懂这些批处理吧。将这些批处理文件放在工作文件夹(即Doxyfile所在文件夹)后。每次仅仅要键入rebuild就能够又一次生成chm文件。必要时能够单独使用clean、build、makechm命令。utf82gbk和html-utf82gbk命令也能够单独使用。
读者能够从我的主页www.fmddlmyy.cn下载这些批处理文件。
3 创建配置文件
3.1 准备工作
“谁养鱼”是我近期写的一个小程序,它用推理法求解爱因斯坦谜题——“谁养鱼”。读者可从《穷举和推理:用C++程序求解“谁养鱼”》下载未文档化的程序。
制作文档前。我们要完毕下面准备工作:
- 安装Doxygen、Graphviz和“HTML Help Workshop”。我使用的HTML Help Workshop版本号是4.74.8702.0。英文版。网上有汉化版本号,但执行时会出错。
- 将iconv和fr程序放到系统路径包括的文件夹。比如c:\windows\system32。
- 建立一个空文件夹fish。放入要凝视的程序(fish\src),建立制作文档的工作文件夹(fish\doc),将前面介绍的批处理文件放到doc文件夹。
好了。如今能够执行Doxywizard创建配置文件。
能够直接点“Save...”button,将配置保存在doc\Doxyfile。这时,Doxyfile的内容是Doxygen的默认设置。Doxyfile是普通文本文件。我们能够直接打开编辑。只是在Doxywizard的界面上填写也非常方便,每一个參数都有具体提示。建议用Doxywizard完毕第一次设置。以后假设须要调整个别參数,能够直接编辑Doxyfile。
3.2 填写參数
点“Expert...”button后,開始填写配置參数。
:),Doxygen是不是有非常多參数?事实上大多数參数都有缺省值。须要填写的不算多,以下分页介绍:
3.2.1 Project页
DOXYFILE_ENCODING是Doxyfile的文本编码。假设文件里有中文字符,能够填写GBK。
填写项目名(PROJECT_NAME)、项目版本号(PROJECT_NUMBER)、输出文件夹(OUTPUT_DIRECTORY)和输出语言(OUTPUT_LANGUAGE)。输出文件夹能够按Doxyfile的相对文件夹填写。输出语言相当于程序资源,选择Chinese。
Doxywizard的中文支持不完好,中文字符会被存为乱码。我们直接编辑Doxyfile。填写:
PROJECT_NAME = 谁养鱼
取消FULL_PATH_NAMES。我们改动了下面參数:
DOXYFILE_ENCODING | GBK |
PROJECT_NAME | 谁养鱼 |
PROJECT_NUMBER | 1.0 |
OUTPUT_DIRECTORY | output |
OUTPUT_LANGUAGE | Chinese |
FULL_PATH_NAMES | NO |
3.2.2 Messages页
在Messages页将WARN_LOGFILE填写为build.log。这样,Doxygen会将编译时出现的警告和错误保存在build.log,我们能够对比改动。
WARN_LOGFILE | build.log |
3.2.3 Input页
指定输入源文件文件夹(INPUT),将输入文件编码(INPUT_ENCODING)改为GBK。
INPUT | ..\src |
INPUT_ENCODING | GBK |
FILE_PATTERNS參数是Doxygen要处理的文件类型,缺省值包含Doxygen支持的全部文件类型。不能用Doxygen文档化随意文件类型。比如Doxygen不支持汇编程序。
3.2.4 Source Browser页
选择SOURCE_BROWSER,在文档中包括源码。
SOURCE_BROWSER | YES |
3.2.5 Html页
选择GENERATE_HTMLHELP后,Doxygen会准备生成chm文件须要的项目文件、文件夹文件和索引文件。
能够通过參数HTML_HEADER和HTML_FOOTER定制页面,參数值是包括定制内容的文件名称。比如。我们能够建立文件html_foot,内容为:
<p align="right"><A HREF="http://www.fmddlmyy.cn/text20.html" target="_top">穷举和推理:用C++程序求解“谁养鱼”</A></p>
</BODY>
</HTML>
然后将HTML_FOOTER的值设为html_foot。
GENERATE_HTMLHELP | YES |
HTML_FOOTER | html_foot |
3.2.6 LaTex页
取消GENERATE_LATEX,不产生LaTex输出。
GENERATE_LATEX | NO |
3.2.7 Dot页
在Dot页,能够选上UML_LOOK、CALL_GRAPH和CALLER_GRAPH。CALL_GRAPH是本函数调用其他函数的示意图,比如:
CALLER_GRAPH是本函数调用者的示意图。比如:
UML_LOOK | YES |
CALL_GRAPH | YES |
CALLER_GRAPH | YES |
3.3 执行Doxygen
对于“谁养鱼”这个样例,其他參数都能够使用缺省值。从命令行进入doc文件夹后(參见附录1)执行rebuild.bat,就能够产生refman.chm。这时,我们还没有对程序作不论什么文档化。输出仅包括Doxygen通过Dot生成的示意图。
我们能够编辑Doxyfile,将EXTRACT_ALL设为YES。再rebuild。这时。Doxygen会自己主动提取程序的全部要素,包含文件、函数、变量、类型定义、枚举、枚举值、宏定义等。
仅仅想看看结果的朋友能够下载这个chm文件。Doxygen配置文件里全部參数的具体參考能够查阅Doxygen手冊中的“Configuration”页。上篇到此结束。下篇将介绍文档化程序的方法。
后记(2007/7/15)
不少朋友说依照我的说明不能产生期待的结果。这一定是我的文章表述不清了,不好意思。近期,我手头事情比較多,这几个月恐怕没时间写本文的下篇了。
好在网上介绍Doxygen文档化的文章还是不少的,少我这篇应该也没什么。
事实上,这篇文章的目的仅仅是让不熟悉doxygen的朋友能够高速地了解这个工具。大家假设真的要使用doxygen,还是应该多花些时间看看它的文档。我把本文范例的工作文件夹打包放在我的主页www.fmddlmyy.cn上,须要的朋友能够下载。
这是个未完毕的版本号,我去掉了EXTRACT_ALL。凝视了几个函数。由于凝视不完整,编译(在doc文件夹rebuild)时还会产生非空的build.log。
log是善意的提示,能够帮助我们完好文档。
附录1 高速进入命令行并转到指定文件夹
假设经经常使用到命令行,能够在注冊表的“HKEY_CLASSES_ROOT\Folder\shell”下建立“Command Prompt Here”项及其子项“command”。将“command”项的默认值设为字符串值“cmd.exe”。这时,仅仅要在资源管理器的随意文件夹上点击右键并选择“Command Prompt Here”就能够高速进入命令行并转到指定文件夹。
我将这个注冊表项保存成reg文件:
Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Folder\shell\Command Prompt Here]
[HKEY_CLASSES_ROOT\Folder\shell\Command Prompt Here\command]
@="cmd.exe"
须要的朋友能够下载后双击导入注冊表就可以。
在vista上。这样操作不能进入指定文件夹,也没有必要这样做。在vista中:仅仅要在资源管理器中先按下shift键。再用右键点击文件夹,就会出现“在此处打开命令窗体”的菜单项,选择就可以。在左側的文件夹树上。这样操作无效。
使用doxygen为C/C++程序生成中文文档的更多相关文章
- Phoenix综述(史上最全Phoenix中文文档)
个人主页:http://www.linbingdong.com 简书地址:http://www.jianshu.com/users/6cb45a00b49c/latest_articles 网上关于P ...
- Chart.js中文文档-雷达图
雷达图或蛛网图(Radar chart) 简介 A radar chart is a way of showing multiple data points and the variation bet ...
- Knockout中文开发指南(完整版API中文文档) 目录索引
a, .tree li > span { padding: 4pt; border-radius: 4px; } .tree li a { color:#46cfb0; text-decorat ...
- ReactNative官方中文文档0.21
整理了一份ReactNative0.21中文文档,提供给需要的reactnative爱好者.ReactNative0.21中文文档.chm 百度盘下载:ReactNative0.21中文文档 来源: ...
- java中文文档官方下载
一直在寻找它,今天无意之间终于发现它了! http://download.oracle.com/technetwork/java/javase/6/docs/zh/api/overview-summa ...
- Spring中文文档
前一段时间翻译了Jetty的一部分文档,感觉对阅读英文没有大的提高(*^-^*),毕竟Jetty的受众面还是比较小的,而且翻译过程中发现Jetty的文档写的不是很好,所以呢翻译的兴趣慢慢就不大了,只能 ...
- jQuery 3.1 API中文文档
jQuery 3.1 API中文文档 一.核心 1.1 核心函数 jQuery([selector,[context]]) 接收一个包含 CSS 选择器的字符串,然后用这个字符串去匹配一组元素. jQ ...
- jQuery EasyUI API 中文文档 - ComboGrid 组合表格
jQuery EasyUI API 中文文档 - ComboGrid 组合表格,需要的朋友可以参考下. 扩展自 $.fn.combo.defaults 和 $.fn.datagrid.defaults ...
- jQuery EasyUI API 中文文档 - ValidateBox验证框
jQuery EasyUI API 中文文档 - ValidateBox验证框,使用jQuery EasyUI的朋友可以参考下. 用 $.fn.validatebox.defaults 重写了 d ...
随机推荐
- 适合ASP.NET Web API使用的场景
富客户端web应用程序:ASP.NET Web API适合大量使用AJAX调用的富客户端应用程序,如Silverlight应用程序,基于Adobe Flash的应用程序或单页应用程序(SPA)等. 本 ...
- JavaScript--数据结构与算法之二叉树
树是一种非线性的数据结构,以分层的方式存储数据. 二叉树:查找非常快,而且二叉树添加或者删除元素也非常快. 形象的可以描述为组织结构图,用来描述一个组织的结构.树是由边连接的点组成.树的一些基本概念: ...
- python实现获取文件列表中每一个文件keyword
功能描写叙述: 获取某个路径下的全部文件,提取出每一个文件里出现频率最高的前300个字.保存在数据库其中. 前提.你须要配置好nltk #!/usr/bin/python #coding=utf-8 ...
- POJ 题目1145/UVA题目112 Tree Summing(二叉树遍历)
Tree Summing Time Limit: 1000MS Memory Limit: 10000K Total Submissions: 8132 Accepted: 1949 Desc ...
- 取消cp命令别名
1. 取消cp命令别名unalias cpcp -rf恢复别名alias cp='cp -i'2.关闭当前用户下的cp别名配置sed -i "s/alias cp='cp -i'/#alia ...
- js03 数组
变量的自动转换=== 等同符:不会发生类型的自动转化! == 等值符:会发生类型自动转化.自动匹配!判断相等没有equals()方法,只有2个等号3个等号. <!DOCTYPE HTML PUB ...
- actionBar-双行字体大小修改
<style name="BackupRestore.Theme.Person" parent="@style/BackupRestore.Theme"& ...
- git 工具的使用总结(5)-查看历史记录
1.查看历史记录git log 1)不加参数,显示的就是节点号,作者,日期,注释 commit b7b310d220628530d1feb9e8046ccb59039d59f2 Author: zha ...
- HDU 2281 Square Number Pell方程
http://acm.hdu.edu.cn/showproblem.php?pid=2281 又是一道Pell方程 化简构造以后的Pell方程为 求出其前15个解,但这些解不一定满足等式,判断后只有5 ...
- 【Oracle错误集锦】:PLSQL无法直连64位Oracle11g数据库
背景:Oracle数据库装在本机上,使用PLSQL连接. 今天安装完Oracle 11g数据库后.用plsql连接数据库死活都连接不上.而且plsql客户端登录窗体的Database下拉框还为空.见下 ...