使用Doxygen 生成帮助文档,并生成chm 格式

doxygen+VIM文档实用指南for C/C/showinfo/c­131849.html摘要：文档撰写是一项十分繁琐而且费力的工作，相信已经有很多人对此深感头痛。

文档生成工具的出现最大限度地帮助程序员解决了这个问题，这些工具通常可以从程序源代码自动生成文档，大大方便了文档工作。

这篇小东西主要介绍了如何用VIM和doxygen来快速生成注释，并用最少的额外劳动来完成专业水准的程序文档的过程。

仅供参考，如有雷同，纯属巧合。

关键字：doxygen vim doxygentoolkit chm dot lex CLanuageScanner补充：本文一开始是为dylan同学准备的，后来有所扩展。

本文不涉及doxygen注释的具体做法，因为可以在网上得到更多关于这方面的范例和资料。

什么是doxygen什么是VIM为什么要使用doxygen+VIM需要做什么？1) 准备工作2) 添加注释3) 配置并运行doxygen4) 编译成chm5) 一些配置选项Dot图形扩展doxygen方便扩展吗？小结什么是doxygendoxygen是一个十分好用的自由软件，是一种文档生成器，其工作机制是利用注释中的有效信息来自动生成文档。

目前doxygen的最新版是(1.5.1)，从 上可以下载最新版的doxygen。

1.5.1版的doxygen可处理的语言包括：l C/C++l Javal Pythonl PHPl Objective­Cl IDL (Corba, Microsoft及KDE­DCOP类型)l C#l D它支持以下文档格式：l HTMLl XMLl LaTeXl RTFl Unix Man Page有了doxygen的支持后，从软件代码到项目文档的转化十分简单，直接执行doxygen可执行程序就可以了。

此时doxygen会在当前目录下寻找默认的配置文Doxyfile(此文件可以手工编写，也可以借助于doxywizard生成)，并从配置文件中读入待解析的文件列表和一些设置，最后生成相应格式的文档。

doxygen使⽤总结doxygen[功能]为许多种语⾔编写的程序⽣成⽂档的⼯具。

[举例]*⽣成⼀个模板配置⽂件，模板⽂件中有详细的注释：$doxgen -g test这样，会⽣成⼀个test⽂件,1500多⾏，可以把这个⽂件做为模板编写配置⽂件。

如果之前有test那么会将原来的test备份为test.bak.模板⽂件的部分内容如下：...前⾯的内容省略...DOXYFILE_ENCODING = UTF-8# The PROJECT_NAME tag is a single word (or a sequence of words surrounded# by quotes) that should identify the project.PROJECT_NAME =# The PROJECT_NUMBER tag can be used to enter a project or revision number.# This could be handy for archiving the generated documentation or# if some version control system is used.PROJECT_NUMBER =# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)# base path where the generated documentation will be put.# If a relative path is entered, it will be relative to the location# where doxygen was started. If left blank the current directory will be used.OUTPUT_DIRECTORY =...后⾯的内容省略...*⽣成⼀个模板配置⽂件，模板⽂件中只有简单的注释：$doxygen -s -g test这⾥，我尝试并且⽐较过，如果使⽤⽣成的⽂件只200多⾏，⼏乎没有注释,只有⼏⾏分类的注释，去除了多余的注释。

简介Doxygen简介Doxygen (1)什么是Doxygen? (1)安装Doxygen (2)设定Project的doxygen组态 (2)撰写正确格式的批注 (6)制作说明文件 (11)什么是Doxygen?Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。

通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。

大部分有用的批注都是属于针对函式，类别等等的说明。

所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。

不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

一个好的程序设计师，在写程序时，都会在适当的地方加上合适的批注。

如果，能够在撰写批注时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的檔。

这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。

Doxygen 就是这样的一个工具。

在您写批注时，稍微按照一些它所制订的规则。

接着，他就可以帮您产生出漂亮的檔了。

因此，Doxygen 的使用可分为两大部分。

首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生檔。

目前Doxygen可处理的程序语言包含：∙C/C++∙Java∙IDL (Corba, Microsoft及KDE-DCOP类型)而可产生出来的檔格式有：∙HTML∙XML∙LaTeX∙RTFUnix Man Page而其中还可衍生出不少其它格式。

如有了LaTeX 档后，就可以透过一些工具产生出PS或是PDF档案。

在多国语言的支持方面，Doxygen 目前可支持的约有2,30种。

自Doxygen 1.2.16开始支持繁体中文(这正是小弟做的好事)。

所以在目前一些Open Source 的程序文件产生器中，Doxygen 算是相当完整的一套。

linux vscode doxygen documentation generator 用法要在Linux上使用VSCode和Doxygen生成文档，您需要按照以下步骤进行操作：安装VSCode：首先，您需要在Linux上安装Visual Studio Code。

您可以从VSCode 官网下载适用于Linux的安装程序，并按照说明进行安装。

安装Doxygen：Doxygen是一个用于生成代码文档的工具。

您可以使用包管理器来安装Doxygen。

例如，在Ubuntu上，您可以使用以下命令安装Doxygen：sqlsudo apt-get install doxygen安装Doxygen插件：在VSCode中，您需要安装Doxygen插件来支持Doxygen文档生成。

打开VSCode，进入扩展商店，搜索Doxygen并安装它。

配置Doxygen：在VSCode中打开您的项目文件夹，并打开名为"Doxyfile"的文件（如果不存在，您可以创建一个）。

在Doxyfile中，您可以配置Doxygen的选项，例如输出格式、目录结构和生成器类型等。

生成文档：配置完成后，打开终端并导航到项目文件夹。

运行以下命令来生成文档：cssdoxygen Doxyfile这将根据Doxyfile中的配置生成文档。

6. 查看文档：生成的文档将保存在指定的输出目录中。

您可以在浏览器中打开生成的HTML文件来查看文档。

请注意，以上步骤是一般性的指导，具体细节可能因您的项目和配置而有所不同。

确保仔细阅读Doxygen和VSCode的文档，并根据您的需求进行适当的配置和调整。

简介Doxygen一．什么是Doxygen？Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。

通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注,与打捞铁达尼号同样的辛苦.大部分有用的批注都是属于针对函式,类别等等的说明。

所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担.不过,反过来说，整理文件的工作对于您来说，就是沉重的负担。

Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。

接着,他就可以帮您产生出漂亮的文档了。

因此，Doxygen 的使用可分为两大部分。

首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

目前Doxygen可处理的程序语言包含：•C/C++•Java•IDL （Corba， Microsoft及KDE-DCOP类型)而可产生出来的文档格式有：•HTML•XML•LaTeX•RTF•Unix Man Page而其中还可衍生出不少其它格式。

HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档。

二．安装Doxygen•1。

1 安装 Doxygen 1。

7。

4(Windows）•1。

2 安装 graphviz 2。

28。

0（Windows)graphviz 是一个由AT＆T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形.Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。

•1。

3 安装 Windows Help Workshop 1。

32Doxygen 使用这个工具可以生成 CHM 格式的文档。

三．Doxygen的配置Doxygen 产生文档可以分为三个步骤.一是在程序代码中加上符合Doxygen所定义批注格式。

二是使用Doxywizard进行配置。

⽂档⽣成⼯具——Doxygen参考： 版权声明：本⽂章转载⾃Jhuster的。

未经作者允许，严禁⽤于商业出版，否则追究法律责任。

⽹络转载请注明出处，这是对原创者的起码的尊重1 简介 为代码写注释⼀直是⼤多数程序员有些困扰的事情。

更头痛的是写⽂档，以及维护⽂档的问题，⽽doxygen就能把遵守某种格式的注释⾃动转化为对应的⽂档。

Doxygen是基于GPL的开源项⽬，是⼀个⾮常优秀的⽂档系统，当前⽀持在⼤多数unix（包括linux），windows家族，Mac系统上运⾏，完全⽀持C++, C, Java, IDL（Corba和Microsoft 家族）语⾔，部分⽀持PHP和C#语⾔，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。

有很多开源项⽬（如log4cpp和CppUnit）都使⽤了doxygen⽂档系统。

2 Doxygen配置⽂件2.1 ⽣成Doxygen配置⽂件 运⾏Doxywizard创建配置⽂件。

可以直接点“Save…”按钮，将保存默认的配置⽂件，名为Doxyfile，内容是Doxygen的默认设置。

Doxyfile是普通⽂本⽂件，可以直接打开⼿动编辑。

不过在Doxywizard的界⾯上填写也很⽅便，每个参数都有详细提⽰。

建议⽤Doxywizard 完成第⼀次设置。

以后如果需要调整个别参数，可以直接编Doxyfile。

上述Doxywizard界⾯中提供了⽣成Doxygen⽂档的4个步骤，按照上述步骤⼀步步执⾏就可以⽣成漂亮的⽂档了。

第⼀步是⽣成配置⽂件，提供三种⽅式：Wizard⽅式指简约⽅式，在其中只提供⼀些重要的参数设置，其余的均为默认值；Expert⽅式为详细设置⽅式，通过该选项可以详细地配置Doxygen的各个配置项；Load⽅式，⽤于导⼊以前⽣成的Doxygen配置⽂件，导⼊后可以再点击Expert进⾏修改。

2.2 配置选项含义详解选项含义DOXYFILE_ENCODING Doxygen⽂件的编码⽅式，默认为UTF-8，若希望⽀持中⽂，最好设置为 GB2312PROJECT_NAME Project 的名字，以⼀个单词为主，多个单词请使⽤双引号括住。

基于Doxygen的代码注释规范一、Doxygen系列软件介绍1、DoxygenDoxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。

注释的语法与Qt-Doc、KDoc和JavaDoc兼容。

Doxgen可以从一套归档源文件开始，生成HTML 格式的在线类浏览器，或离线的LATEX、RTF参考手册。

Doxygen能将程序中的特定批注转换成为说明文件。

它可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图（include dependency graphs）、继承图（inheritance diagram）以及协作图（collaboration diagram）来可视化文档之间的关系， Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。

2、graphvizGraphviz(Graph Visualization Software)是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。

要使用Doxygen生成依赖图、继承图以及协作图，必须先安装graphviz软件。

3、HTML Help WorkShop微软出品的HTML Help WorkShop是制作CHM文件的最佳工具，它能将HTML 文件编译生成CHM文档。

Doxygen软件默认生成HTML文件或Latex文件，我们要通过HTML生成CHM 文档，需要先安装HTML Help WorkShop软件，并在Doxygen中进行关联。

二、软件下载与安装Doxygen下载（doxygen-1.8.7-setup.exe）：http://www.stack.nl/~dimitri/doxygen/download.htmlgraphviz（for windows）下载：/Download..phpHTML Help WorkShop（1.32）下载：/download/0/a/9/0a939ef6-e31c-430f-a3df-dfae7960d564/htmlhelp.exe软件安装都选择默认方式，点击下一步直至安装完成。

doxygen⽣成源码⽂档使⽤doxygen ⽣成源代码的⽂档是相当⽅便的，本⽂就简单整理下doxygen的使⽤说明1. 安装　关于安装的问题不做特殊的说明，这⾥直接使⽤命令安装，源码安装不做介绍ubuntu:　sudo apt-get install doxygencentossudo yum install doxygen2. 配置⽂件配置　关于doxygen主要的部分就在于配置⽂件的配置， doxygen相当强⼤，所以配置⽂件内容有点多。

这⾥只介绍⼀部分，⼤家有兴趣可以继续深⼊研究　(1) 重要标记 配置⽂件采⽤ <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 就会这样做。

⾃动⽣成帮助⽂档⼯具——Doxygen的使⽤⽰例（C++）在项⽬中⽤了Doxygen来制作⽂档，记录备忘。

查了不少⽂章，主要使⽤⽅法及例⼦参考都是来⾃以下链接：使⽤步骤：⼀、安装内容1 安装 Doxygen(Windows)2 安装 graphviz(Windows)　因为项⽬⽐较⼩所以没有安装graphviz3 安装 Windows Help Workshop　要⽣成 CHM 格式的⽂档需安装⼆、配置Doxygen1 写的代码注释很多都是中⽂的，如果源码是GB2312格式，记得转为UTF-8格式。

直接输⼊GB2312格式没有尝试。

2 Export Label 下的HTML选项中，CHM_INDEX_ENCODING选项要使⽤GB2312，否则⽣成的CHM中会显⽰乱码。

（实际上在使⽤CHM 中的搜索功能时仍存在乱码，未解决）3 记住要添加 hhc.exe 的路径。

三、代码⽰例此⽰例在链接⽰例基础上修改，简单的注释变量、函数、类等基本够⽤了。

注释应该还有⼀些其他的功能，有时间需要深⼊了解⼀下。

PS:例如想插⼊⼀些调⽤函数的⽰例代码。

.h/*** @file** 此⽂件⽤于定义class example**@auther ...*////定义EXAMPLE_OK的宏为0#define EXAMPLE_OK 0/*** @brief 类的简短说明** 此类⽤于doxygen的使⽤说明**/class Example {private:///变量var1int var1;public:///变量var2int var2;///变量var3int var3;void ExFunc1(void);void int ExFunc2(int a,char b);char *ExFunc3(char *c);}View Code.cpp/*** @file** 此⽂件⽤于定义example class 的 * member function** @author ...*//*** @brief ExFunc1 的简易说明** ExFunc1没有任何参数及返回值*/void Example::ExFunc1(void){//code}/*** @brief ExFunc2 的简易说明** ExFunc2()传回两个参数相加的值 ** @param a ⽤来相加的参数* @param b ⽤来相加的参数* @return 传回两个参数相加的结果 */int Example::ExFunc2(int a,int b){return(a+b);}/*** @brief ExFunc3的简易说明** ExFunc3()只传回参数输⼊的指标。

一款常用文档生成工具：Doxygen程序员的很多文档，特别是有代码的文档，绝大部分都是由一款文档生成工具【Doxygen】生成。

什么是Doxygen?Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。

通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。

大部分有用的批注都是属于针对函式，类别等等的说明。

所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用你的程序代码的人而言将会减少许多的负担。

不过，反过来说，整理文件的工作对于你来说，就是沉重的负担。

简而言之，Doxgen就是大名鼎鼎的文档生成工具，而且是免费开源的，它使用非常方便，能提取C++，Java，Objective-C，Python，IDL，PHP，C#等语言的注释，从而生成文档。

Doxygen 的使用可分为两大部分。

首先是特定格式的批注撰写，第二便是利用Doxygen的工具来生成文档。

生成文档使用教程1、安装在Linux下可以通过apt install doxygen安装命令行工具，然后用apt install doxygen-gui安装图形界面。

对Linux用户来说，命令行工具可以通过doxygen命令运行，而图形界面可以通过doxywizard命令运行。

Windows 用户的下载地址：/download.html2、基本使用图形工具的基本使用如下图所示，有非常多的配置选项，这里我们只填入必要的配置，其它配置都用默认值。

doxywizard使用步骤doxywizard使用步骤工作目录如下：.├── out└── src└── math.h其中math.h代码如下：/*! \file math.h *//*!用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示\li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角\li 角度制用d结尾，例如：360d表示一圈、90d表示直角\li 输入也可以是数值，例如：输入3.14159大约表示180度\param a 用弧度制或角度制表示都行，字符串必须用'\0'表示结束\param[out] res 是输出参数，用于保存sin运算的结果\return 错误码，0表示成功，其它表示失败\todo 在xxx的情况下存在BUG，预计下一版本修复*/int sin(char *a, double *res);Doxygen生成的HTML会放到out目录下，生成的HTML如下图所示。

Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage，Doxygen软件可以从这里下载，软件本身用法非常简单。

这里不做介绍，下面主要是代码中doxygen 的注释的写法的介绍。

1. 模块定义（单独显示一页）/** @defgroup 模块名模块的说明文字* @{*/… 定义的内容…/** @} */ // 模块结尾2. 分组定义（在一页内分组显示）/** @name 分组说明文字* @{*/… 定义的内容…/** @} */3. 变量、宏定义、类型定义简要说明/** 简要说明文字 */#define FLOAT float/** @brief 简要说明文字（在前面加 @brief 是标准格式） */#define MIN_UINT 0/** 分行的简要说明 \n* 这是第二行的简要说明*/int b;4. 函数说明/** 简要的函数说明文字* @param [in] param1 参数1说明* @param [out] param2 参数2说明* @return 返回值说明*/int func(int param1, int param2);/** 打开文件 \n* 文件打开成功后，必须使用 ::CloseFile 函数关闭。

* @param[in] file_name 文件名字符串* @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成：* – r 读取* – w 可写* – a 添加* – t 文本模式(不能与 b 联用)* – b 二进制模式(不能与 t 联用)* @return 返回文件编号* – -1 表示打开文件失败* @note 文件打开成功后，必须使用 ::CloseFile 函数关闭* @par 示例:* @code// 用文本只读方式打开文件int f = OpenFile(”d:\\test.txt”, “rt”);* @endcode* @see ::ReadFile ::WriteFile ::CloseFile* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。

Doxygen安装及使用手册一简介Doxygen可以从C，C++，java等源代码中提取消息来生成帮助文档，API资料等二下载Doxygen以下，是在linux平台下的demo介绍。

http://www.stack.nl/~dimitri/doxygen/index.htmldoxyen主页去下载doxygen-1.5.5.src.tar.gz三 Doxygen安装安装doxygen-1.5.5.src.tar.gz1 把下载好的doxygen-1.5.5.src.tar.gz拷到自己想要的目录中，我放到了自己的Home目录下。

2 进入相应的目录：本例是在自己的home目录下3 解压#tar -zxvf doxygen-1.5.5.src.tar.gz会在当前目录下生成一个名字为doxygen-1.5.5的目录。

4 在自己的Home目录下建立一个doxygen目录，我们的doxygen以后就安装到这个目录下。

#mkdir doxygen5 进入doxygen-1.5.5目录#cd doxygen-1.5.56 安装：用—prefix选项制定安装目录为/home/lvq/doxygen，lvq为我的用户名，这里可以用~/doxygen代替。

#./configure –prefix ~/doxygen#make#make install这样在~/doxygen 目录就安装好了doxygen软件7 生成配置文件#cd ~/doxygen/bin/# ./doxygen –g 文件名执行这个命令后就会生成一个制定名字的配置文件，这里我们不加文件名，只用./doxygen –g 生成默认配置文件Doxyfile。

四如何使用DoxygenDoxygen可以从源代码中提取消息生成帮助文档，它是根据源代码中的特定注释来实现。

所以，首先要给工程代码书写符合Doxygen格式的注释。

1 以sipproxy小工程为例1)这个工程在/home/lvq/self/sipproxy1/sipproxy-v1.04/目录下。

方法一：使用doxygen为C/C++程序生成中文文档转自按照约定的格式注释源代码，用工具处理注释过的源代码产生文档。

通过这种方式产生文档至少有以下好处：∙便于代码和文档保持同步。

∙可以对文档做版本管理。

很多编程语言都有类似的文档工具，例如：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生成文档，主要是两件事：1.写一个配置文件（Doxyfile）。

一般用Doxywizard生成后，再手工修改。

2.按照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 需要什么完成本文的范例需要以下工具：1.Doxygen的最新版本，可以从Doxygen的网站下载。