doxys是开源软件, 文章最后给的链接里的doxys.exe是debug版本,还有个配置文件,感兴趣的朋友可以打开链接下载,按照下面的方法使用即可。
一、更改配置:打开DoxySfile,设置INPUT(源码路径)、OUTPUT_DIRECTORY(输出路径)、OUTPUT_LANGUAGE(语言选择----界面语言)
如果是中文界面,只要改变INPUT和OUT_DIRECTORY的路径就可以。
二、生成文档:进入MS-DOS,切换到doxys.exe所在的路径,执行doxys DoxySfile -m就可产生帮助文档,不过都是html。
三、制作CHM文档:进入到配置文件中的OUTPUT_DIRECTORY(输出路径)下,在common目录,打开js.js,搜索一下“http://www.doxys.dk”,
将有这已经的代码行注释掉(这行在页面上产生“产生 DoxyS”链接,它的直接结果就是产生doxys的英文帮助)。
最后单击.hhc或.hhk或.hhp文件,在File菜单下点击“compile”,就可以产生.chm文件。
四、其他:必须的安装文件还有htmhtlp.exe.
附录:编写注释规范
一、函数注释:
/**
\brief
简短注释
\n
* @param[in] 输入参数
* @param[out] 输出参数
* @return 返回值
* @note 注解
* @par 示例
* @code 代码
* @endcode
* @see 参见
* @deprecated 相关信息
也可以在@param后面直接跟参数
示例:函数OpenFile的注释
/**
\brief file_文件
打开文件 \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 由于特殊的原因,这个函数可能会在将来的版本中取消。
*/
int OpenFile(const char* file_name, const char* file_mode);
二、变量注释:
/** 成员变量描述 */
int m_Var;
三、宏定义注释:
/** 定义说明 */
#define LOG_FILENAME "d:\\log\\debug.log"
在宏定义中我们也可以分组展示:就是在一组的宏定义前面和后面分别加注释
前面加:
/** @name 文件名常量
* @{
*/
后面加:
/** @}*/ // 文件名常量
如下所示:
/** @name 文件名常量
* @{
*/
/** 日志文件名 */
#define LOG_FILENAME "d:\\log\\debug.log"
/** 数据文件名 */
#define DATA_FILENAME "d:\\data\\detail.dat"
/** 存档文件名 */
#define BAK_FILENAME "d:\\data\\backup.dat"
/** @}*/ // 文件名常量
四、枚举注释:
/** 枚举常量 */
typedef enum TDayOfWeek
{
SUN = 0, /**< 星期天 */
MON = 1, /**< 星期一 */
TUE = 2, /**< 星期二 */
WED = 3, /**< 星期三 */
THU = 4, /**< 星期四 */
FRI = 5, /**< 星期五 */
SAT = 6 /**< 星期六 */
}
五、类注释:
1、类的简短说明:放到类声明(Yourclass.h)最前面
/*!\file
\brief Yourclass类封装了对象的属性及对属性的操作
*/
.......
.......
class Yourclass{
.........
};
2、类的详细说明:在类简短说明下面
/** \file
\brief 每个CPerson类对象包含问题规定的对象属性
* @author 作者
* @version 版本号
* @date 日期
在“谁养鱼”问题中,每个对象包含属性:国籍、颜色、宠物、饮料、香烟、房间号。不过CPerson并不关心属性的含义。
属性对CPerson来说只是序号和值。
*/
六、结构体/联合体:
/** A test class. 结构体简要说明. */
typedef struct TWeek
{
int a; //!< 星期天
int b;//!<星期一
int c; //!<星期二
};
下面的链接是doxys.exe、DoxySfile和htmlhelp.exe,doxys.exe是debug版本的比较大,DoxySfile是配置文件,如果搭建懒得写,改改这个示例的配置文件就行,方法如上所示。
http://www.vdisk.cn/down/index/4361526A7291
Doxygen相关设置
首先在“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)