如何用doxygen生成cocos2d-x文档
2015-11-06 20:25
513 查看
转自:http://blog.csdn.net/hitlion2008/article/details/8648253
Doxygen是一种开源跨平台的工具,其功能是从程序源代码中抽取类、方法、成员的注 释,形成一个和源代码配套的API(Application Programming Interface,应用程序编程接口)帮助文档。Doxygen工具,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、 Objective-C等语言,部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开 始,生成HTML格式的在线类浏览器(或.chm格式),或离线的LATEX、RTF参考手册。
Doxygen可以根据代码中的注释,按照规则生成相应的文档。Cocos2D-x的代码就依照了它的规则,并且提供了doxygen.config文件。这是Cocos2D-x代码的Doxygen配置文档,可以通过这个文件来生成Cocos2D-x文档。
首先下载Doxygen,下载地址为http://www.doxygen.nl/download.html#latestsrc。根据系统选择要下载的版本,建议下载安装版。下载完成后运行程序,出现如图2-42所示的界面。
使用File→Open打开cocos2d-x-2.1.4\cocos2d-x-2.1.4\目录下的document目录下的doxygen.config文件,界面如图2-43所示。
(在wizard菜单下,对于“project”标签,设置对应的doxygen的工作路径、源代码的路径、生成的doc的路径、软件的版本号等,可以将工程src目录拷贝到单独的文件夹下。)
在wizard菜单下,对于“output”标签,设置生成文件的格式为.chm。
在expert菜单下,对于“HTML”标签下,勾选’GENNERATE_HTMLHELP’,并且设置生成的.chm文件的名称,此时就需要使 用“html help workshop”软件的hhc.exe,在“HHC_LOCATION”下输入hhc.exe文件的路径,通常情况下为“C:\Program Files\HTML Help Workshop”。(我的hhc.exe的文件路径是D:/Program Files/HTML Help Workshop/hhc.exe)
打开配置文件后出现了Cocos2D-x版本配置信息,单击“Run”选项卡,单击“Run doxygen”按钮,运行生成文档,完成后如图2-44所示。生成.html文档和.chm文档需要一段时间,耐心等待!
打开Cocos2D-x目录下的cocos2d-x-2.1.4\cocos2d-x-2.1.4\document\目录下的index.html和index.chm文件,如图所示,可以使用Cocos2D-x文档了。
Doxygen是一款基于源代码生成文档的工具,类似于Java中的javadoc.
是给代码的使用者准备的,或者是更高一级的开发者或者是用户,主要是告诉使用者如何更好的使用代码.典型例子就是API文档.
代码的一部分,解释代码为什么这样写,是给代码的维护者准备的.
优秀且可读的代码应该不需要注释,但文档应该是必须有的,特别是API文档.
这个是第一步,也是最重要的一步,直接影响着文档的优与劣.
Doxygen是一个比较成熟的工具了,它有非常详细且专业的文档.
文档是写在代码当中的,以注释块的形式,为了区分代码中的正常注释,访文档需要用特殊的形式的注释块来呈现.Doxygen支持多种文档注释块:
Javadoc形式的:
[cpp] view
plaincopyprint?
/**
* ...
*/
QT形式的
[cpp] view
plaincopyprint?
/*!
* ...
*/
或者,这样
[cpp] view
plaincopyprint?
///
/// ...
///
或者,这样
[cpp] view
plaincopyprint?
//!
//! ..
//!
后二种有点非主流,不建议使用.推荐使用前面二种.当然,配置了某些特殊的选项也可以使用其他格式.
当Doxygen看到这种形式的注释块时就会把它从代码中抽取出来,生成HTML形式的文档.
为了让文档更且有可读性,表达出更多的信息,Doxygen就定义了很多的命令,常用的有:
\file 告诉Doxygen这是某个文件的文档块
\enum 给一个enum类型加文档
\struct 给一个结构体加文档
\param 函数的参数
\return 函数的返回值
\see 交叉参考
\brief 简介,用于概览时控制在一行以内,可以空一行,然后写更多的详细的内容
\code \endcode 示例代码
\note 注意事项
\par HTML中的<p>
需要注意的是,这些命令也可以用javadoc格式的来写如@file, @enum, @return等.但建议用标准格式,因为\只需要敲一下,而@需要敲二下,另外就是并不是所有的命令都支持javadoc格式.
还有就是如果想写交叉引用可以在前面加个#就会自动转为相应的链接,直接上个例子就都明白了:
[cpp] view
plaincopyprint?
/**
* \brief Obtain current list of path
*
* \param [out] paths a pointer to an array of strings
* \param [out] count indicating the count of path.
*
* \note
* This function will allocate memory for path array. So caller must free the array, but should not free each item.
*
* \return #API_RESULT_CODE indicating whether this call success or failed.
*
* \par Sample code:
* \code
* char **path = NULL;
* int count = 0;
* test_get_paths(&path, &count);
* // use the path
* free(path);
* path = NULL;
* \endcode
*/
int test_get_paths(char ***paths, int *count);
Doxygen需要一个配置文件来告诉Doxygen一些选项.配置文件就是一个纯文本文件,格式跟标准的Linux配置文件一样:一行一个配置项,前面是配置项的名字,然后是等号后面就是配置项的值了.以#开头都是注释.Doxygen的选项特别的多,不可以手动的去写,通常都是编辑一个现有的模板,这个模板可以用Doxygen来生成:
doxygen -g config-filename
config-filename就是生成的配置文件模板,每个配置项前面都有一大段文档详细说明用途以及如何修改.绝大多数配置项是不需要修改的,仅有一些常用的需要修改:
PROJECT_NAME 项目的名字,一定要改成你项目的名字
PROJECT_NUMBER 编号,通常使用项目的版本号
OUTPUT_DIRECTORY 文档输出存放目录,建议修改,比如doc
PROJECT_BRIEF 项目的描述,会出现文档每一页的上面,控制在一行80字符内(越短越好)
EXTRACT_*** 打头的选项要仔细读,如果是API文档,则这些全都要设成NO,这样就仅抽取特定文档块内的内容.
其他的选项都可以不改,用默认的就成.
这步最简单,如果前面都就绪了,仅需要运行命令即可:
doxygen config-filename
后,文档就会出现在所指定的输出目录中.
doxygen会打印出日志信息.为了保证质量,最好把把的Warning都修正掉.(这跟修正代码的所有编译警告一个道理).
上面例子生成的文档:
Obtain current list of path.
Parameters:
Note:This function will allocate memory for path array. So caller must free the array, but should not free each item.
Returns:API_RESULT_CODE indicating whether this
call success or failed.
Sample code:
完整示例下载
2010年曾经使用Doxygen生成全中文的chm文档。由于Doxygen生成的chm目录文件(index.hhc)本身是使用UTF-8编码的,而古老的chm编译器(HTML Help Workshop)对于CHM控制文件(index.hhc、index.hhk、index.hhp),却只支持ANSI编码(即本地编码,如中文系统为GBK),所以最终编译出来的chm文件,左边的目录导航栏全是乱码。为了解决这个问题,可费了一番工夫,得先使用编码转换工具转换后再用chm编译器编译(见:使用doxygen为C/C++程序生成中文文档)。
今天重新拿起Doxygen,惊喜地发现,它已经支持生成ANSI编码的chm目录文件(index.hhc)了,所以能省好多工夫,现在终于可以一步搞定。现在想来,Doxygen早就应该支持这个功能的,做起来也很简单——当然我没有详细去翻查Doxygen是从哪个版本开始支持的,反正Doxygen 1.8.0是支持的,想必之后的版本都支持。
到 Doxygen 官网 下载最新的Doxygen安装程序,然后安装。这个软件包包括了一个GUI界面的前端工具,可以帮助我们方便创建Doxygen配置文件和生成目标文档。
下面以 Doxygen 1.8.0 为例进行讲解。
我们使用微软古老的 HTML Help Workshop 1.3,这个软件N久没更新了。
下载地址: 微软官网
下载后根据提示安装。
首先在“Wizard”标签的Project项进行如下设置:
项目名称:将在最新的文档首页中显示
源码列表:选择要生成文档的源代码或目录,可以有多个文件或目录形成一个列表。建议使用相对路径,相对于当前目录(也即当前配置文件所在的目录)
递归扫描:如果需要对整个源码目录下的所有子目录及文件生成文档,请勾选本项
输出目录:设置最终生成的帮助文档的存储路径,建议使用相对路径
下一步,Mode项,根据需要设置文档生成模式。
下一步,Output项,设置输出格式,勾选HTML和“prepare for compressed HTML(.chm)”
然后切换到“Expert”标签的“HTML”项,设置HTML和CHM相关的选项:
GENERATE_HTMLHELP:确保已经勾选了
CHM_FILE:最终生成的.chm的文件名,如“HkcProjectHelp.chm”。默认为“index.chm”。可以使用路径,也可以使用相对路径,相对于上面设置的输出目录的html目录(建设使用上一级目录,如“..\MyDoc.chm”)
HHC_LOCATION:chm 编译器(hhc.exe)的全路径。请指到 HTML Help Workshop 的安装目录的 hhc.exe 程序
CHM_INDEX_ENCODING:chm索引文件编码,下面会讲到,这里填“GBK”
编码设置很重要,如果设置不当,生成的文档会出现乱码。因为 Doxygen 汲及的东西多,有好几项编码设置,所以需要认真对待,根据项目的实情情况设置。
所有高级设置(包括编码设置)都在“Expert”标签,重要的设置项如下:
Project/DOXYFILE_ENCODING:当前 Doxygen 配置文件本身的字符编码,默认为UTF-8,一般不需要修改
Project/OUTPUT_LANGUAGE:输出语言。这里是指Doxygen自己生成的导航、提示、帮助等文本的文字采用的语言。我们希望帮助文档是全中文的,所以选择Chinese
Input/INPUT_ENCODING:输入文件的编码。这里是指我们的源代码文件本身的编码。在Windows平台一般是系统编码(GBK),而Linux平台一般是UTF-8。请用文本编辑器查看源文件的编码。这里如果设置的不一致,源码文件的注释中所有非ASCII字符将在生成的文档中变成乱码。
HTMP/CHM_INDEX_ENCODING:这里设置Doxygen生成的CHM索引文件的编码,以前是不能设置的,默认为UTF-8,而微软的编译器不能识别UTF-8编码的索引文件,所以最终造成左边目录导航栏乱码。我们设置它为GBK,这样Doxygen将为我们生成GBK编码的索引文件(.hhc、.hhk、.hhp)
设置好了后,点击“Run”→“Run doxygen”生成最终的.chm文档,如果设置正确,打开后是全中文的了。
Doxygen是一种开源跨平台的工具,其功能是从程序源代码中抽取类、方法、成员的注 释,形成一个和源代码配套的API(Application Programming Interface,应用程序编程接口)帮助文档。Doxygen工具,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、 Objective-C等语言,部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开 始,生成HTML格式的在线类浏览器(或.chm格式),或离线的LATEX、RTF参考手册。
Doxygen可以根据代码中的注释,按照规则生成相应的文档。Cocos2D-x的代码就依照了它的规则,并且提供了doxygen.config文件。这是Cocos2D-x代码的Doxygen配置文档,可以通过这个文件来生成Cocos2D-x文档。
首先下载Doxygen,下载地址为http://www.doxygen.nl/download.html#latestsrc。根据系统选择要下载的版本,建议下载安装版。下载完成后运行程序,出现如图2-42所示的界面。
使用File→Open打开cocos2d-x-2.1.4\cocos2d-x-2.1.4\目录下的document目录下的doxygen.config文件,界面如图2-43所示。
(在wizard菜单下,对于“project”标签,设置对应的doxygen的工作路径、源代码的路径、生成的doc的路径、软件的版本号等,可以将工程src目录拷贝到单独的文件夹下。)
在wizard菜单下,对于“output”标签,设置生成文件的格式为.chm。
在expert菜单下,对于“HTML”标签下,勾选’GENNERATE_HTMLHELP’,并且设置生成的.chm文件的名称,此时就需要使 用“html help workshop”软件的hhc.exe,在“HHC_LOCATION”下输入hhc.exe文件的路径,通常情况下为“C:\Program Files\HTML Help Workshop”。(我的hhc.exe的文件路径是D:/Program Files/HTML Help Workshop/hhc.exe)
打开配置文件后出现了Cocos2D-x版本配置信息,单击“Run”选项卡,单击“Run doxygen”按钮,运行生成文档,完成后如图2-44所示。生成.html文档和.chm文档需要一段时间,耐心等待!
打开Cocos2D-x目录下的cocos2d-x-2.1.4\cocos2d-x-2.1.4\document\目录下的index.html和index.chm文件,如图所示,可以使用Cocos2D-x文档了。
Doxygen是一款基于源代码生成文档的工具,类似于Java中的javadoc.
概念:文档和注释的区别
文档(Documentation)
是给代码的使用者准备的,或者是更高一级的开发者或者是用户,主要是告诉使用者如何更好的使用代码.典型例子就是API文档.
注释
代码的一部分,解释代码为什么这样写,是给代码的维护者准备的.优秀且可读的代码应该不需要注释,但文档应该是必须有的,特别是API文档.
在代码中加入文档
这个是第一步,也是最重要的一步,直接影响着文档的优与劣.Doxygen是一个比较成熟的工具了,它有非常详细且专业的文档.
文档是写在代码当中的,以注释块的形式,为了区分代码中的正常注释,访文档需要用特殊的形式的注释块来呈现.Doxygen支持多种文档注释块:
Javadoc形式的:
[cpp] view
plaincopyprint?
/**
* ...
*/
QT形式的
[cpp] view
plaincopyprint?
/*!
* ...
*/
或者,这样
[cpp] view
plaincopyprint?
///
/// ...
///
或者,这样
[cpp] view
plaincopyprint?
//!
//! ..
//!
后二种有点非主流,不建议使用.推荐使用前面二种.当然,配置了某些特殊的选项也可以使用其他格式.
当Doxygen看到这种形式的注释块时就会把它从代码中抽取出来,生成HTML形式的文档.
为了让文档更且有可读性,表达出更多的信息,Doxygen就定义了很多的命令,常用的有:
\file 告诉Doxygen这是某个文件的文档块
\enum 给一个enum类型加文档
\struct 给一个结构体加文档
\param 函数的参数
\return 函数的返回值
\see 交叉参考
\brief 简介,用于概览时控制在一行以内,可以空一行,然后写更多的详细的内容
\code \endcode 示例代码
\note 注意事项
\par HTML中的<p>
需要注意的是,这些命令也可以用javadoc格式的来写如@file, @enum, @return等.但建议用标准格式,因为\只需要敲一下,而@需要敲二下,另外就是并不是所有的命令都支持javadoc格式.
还有就是如果想写交叉引用可以在前面加个#就会自动转为相应的链接,直接上个例子就都明白了:
[cpp] view
plaincopyprint?
/**
* \brief Obtain current list of path
*
* \param [out] paths a pointer to an array of strings
* \param [out] count indicating the count of path.
*
* \note
* This function will allocate memory for path array. So caller must free the array, but should not free each item.
*
* \return #API_RESULT_CODE indicating whether this call success or failed.
*
* \par Sample code:
* \code
* char **path = NULL;
* int count = 0;
* test_get_paths(&path, &count);
* // use the path
* free(path);
* path = NULL;
* \endcode
*/
int test_get_paths(char ***paths, int *count);
配置Doxygen
Doxygen需要一个配置文件来告诉Doxygen一些选项.配置文件就是一个纯文本文件,格式跟标准的Linux配置文件一样:一行一个配置项,前面是配置项的名字,然后是等号后面就是配置项的值了.以#开头都是注释.Doxygen的选项特别的多,不可以手动的去写,通常都是编辑一个现有的模板,这个模板可以用Doxygen来生成:doxygen -g config-filename
config-filename就是生成的配置文件模板,每个配置项前面都有一大段文档详细说明用途以及如何修改.绝大多数配置项是不需要修改的,仅有一些常用的需要修改:
PROJECT_NAME 项目的名字,一定要改成你项目的名字
PROJECT_NUMBER 编号,通常使用项目的版本号
OUTPUT_DIRECTORY 文档输出存放目录,建议修改,比如doc
PROJECT_BRIEF 项目的描述,会出现文档每一页的上面,控制在一行80字符内(越短越好)
EXTRACT_*** 打头的选项要仔细读,如果是API文档,则这些全都要设成NO,这样就仅抽取特定文档块内的内容.
其他的选项都可以不改,用默认的就成.
生成文档
这步最简单,如果前面都就绪了,仅需要运行命令即可:doxygen config-filename
后,文档就会出现在所指定的输出目录中.
doxygen会打印出日志信息.为了保证质量,最好把把的Warning都修正掉.(这跟修正代码的所有编译警告一个道理).
上面例子生成的文档:
int test_get_paths | ( | char *** | paths, |
int * | count | ||
) |
Parameters:
[out] | paths | a pointer to an array of strings |
[out] | count | indicating the count of path. |
Returns:API_RESULT_CODE indicating whether this
call success or failed.
Sample code:
<span class="keywordtype">char</span> **path = NULL; <span class="keywordtype">int</span> count = 0; <a target=_blank class="code" href="file:///media/sharedspace/work/libofono-api/doxygen/doc/html/test_8h.html#ae0a399d739a3405f45457c669b7bab9f" title="Obtain current list of path." style="color: rgb(51, 102, 153); text-decoration: none;">test_get_paths</a>(&path, &count); <span class="comment">// use the path</span> free(path); path = NULL;
完整示例下载
2010年曾经使用Doxygen生成全中文的chm文档。由于Doxygen生成的chm目录文件(index.hhc)本身是使用UTF-8编码的,而古老的chm编译器(HTML Help Workshop)对于CHM控制文件(index.hhc、index.hhk、index.hhp),却只支持ANSI编码(即本地编码,如中文系统为GBK),所以最终编译出来的chm文件,左边的目录导航栏全是乱码。为了解决这个问题,可费了一番工夫,得先使用编码转换工具转换后再用chm编译器编译(见:使用doxygen为C/C++程序生成中文文档)。
今天重新拿起Doxygen,惊喜地发现,它已经支持生成ANSI编码的chm目录文件(index.hhc)了,所以能省好多工夫,现在终于可以一步搞定。现在想来,Doxygen早就应该支持这个功能的,做起来也很简单——当然我没有详细去翻查Doxygen是从哪个版本开始支持的,反正Doxygen 1.8.0是支持的,想必之后的版本都支持。
下载和安装 Doxygen
到 Doxygen 官网 下载最新的Doxygen安装程序,然后安装。这个软件包包括了一个GUI界面的前端工具,可以帮助我们方便创建Doxygen配置文件和生成目标文档。下面以 Doxygen 1.8.0 为例进行讲解。
下载和安装 chm 编译器
我们使用微软古老的 HTML Help Workshop 1.3,这个软件N久没更新了。下载地址: 微软官网
下载后根据提示安装。
项目一般设置
首先在“Wizard”标签的Project项进行如下设置:项目名称:将在最新的文档首页中显示
源码列表:选择要生成文档的源代码或目录,可以有多个文件或目录形成一个列表。建议使用相对路径,相对于当前目录(也即当前配置文件所在的目录)
递归扫描:如果需要对整个源码目录下的所有子目录及文件生成文档,请勾选本项
输出目录:设置最终生成的帮助文档的存储路径,建议使用相对路径
下一步,Mode项,根据需要设置文档生成模式。
下一步,Output项,设置输出格式,勾选HTML和“prepare for compressed HTML(.chm)”
然后切换到“Expert”标签的“HTML”项,设置HTML和CHM相关的选项:
GENERATE_HTMLHELP:确保已经勾选了
CHM_FILE:最终生成的.chm的文件名,如“HkcProjectHelp.chm”。默认为“index.chm”。可以使用路径,也可以使用相对路径,相对于上面设置的输出目录的html目录(建设使用上一级目录,如“..\MyDoc.chm”)
HHC_LOCATION:chm 编译器(hhc.exe)的全路径。请指到 HTML Help Workshop 的安装目录的 hhc.exe 程序
CHM_INDEX_ENCODING:chm索引文件编码,下面会讲到,这里填“GBK”
编码设置
编码设置很重要,如果设置不当,生成的文档会出现乱码。因为 Doxygen 汲及的东西多,有好几项编码设置,所以需要认真对待,根据项目的实情情况设置。所有高级设置(包括编码设置)都在“Expert”标签,重要的设置项如下:
Project/DOXYFILE_ENCODING:当前 Doxygen 配置文件本身的字符编码,默认为UTF-8,一般不需要修改
Project/OUTPUT_LANGUAGE:输出语言。这里是指Doxygen自己生成的导航、提示、帮助等文本的文字采用的语言。我们希望帮助文档是全中文的,所以选择Chinese
Input/INPUT_ENCODING:输入文件的编码。这里是指我们的源代码文件本身的编码。在Windows平台一般是系统编码(GBK),而Linux平台一般是UTF-8。请用文本编辑器查看源文件的编码。这里如果设置的不一致,源码文件的注释中所有非ASCII字符将在生成的文档中变成乱码。
HTMP/CHM_INDEX_ENCODING:这里设置Doxygen生成的CHM索引文件的编码,以前是不能设置的,默认为UTF-8,而微软的编译器不能识别UTF-8编码的索引文件,所以最终造成左边目录导航栏乱码。我们设置它为GBK,这样Doxygen将为我们生成GBK编码的索引文件(.hhc、.hhk、.hhp)
生成CHM文档
设置好了后,点击“Run”→“Run doxygen”生成最终的.chm文档,如果设置正确,打开后是全中文的了。
相关文章推荐
- Cocos2d-x游戏开发——Lua语言入门(安装、测试)
- cocos-lua基础学习(四)quick层封装后的目录结构
- cocos2dx3.4 VS2012无法打开包含文件extensions/ExtensionExport.h
- cocos2d-x 架构和引擎目录
- 【cocos2d-js系列问题】cocos2d-js 获取cocostudio中的UI组件
- cocos2d-x 3.8.1 Widget 置灰的实现
- Quick-Cocos2d-x 如何入门
- 【cocos2d-js系列问题】win7 Cocos2d-js 报Uncaught Error: child already added. It can't be added again 错误解决
- 【cocos2d-js系列问题】win7 cocos2d-js 报ccs is not defined错误解决
- Cocos2d-x高级篇——Cocos3D前生今世
- cocos2d-x打包Android
- cocosJs 学习文章 地址
- cocos2d-x 学习笔记(一)
- cocos2d-x Programmers Guide v3.3 译本和阅读笔记(第3章:精灵)
- Cocos2dx3.0过渡篇 各种遍历与范围for语句的使用【转】
- cocos2dx中retain和release
- cocos2dx shader
- 细说Cocos2d-JS——从项目构造说起
- cocos code ide--js config.json文件结构
- Cocos2d-x 中加载骨骼动画资源