Benjamin

静以修身,俭以养德,非澹薄无以明志,非宁静无以致远。
随笔 - 388, 文章 - 0, 评论 - 196, 引用 - 0
数据加载中……

编写C++帮助文档的工具-----doxys使用方法

doxys是开源软件,  文章最后给的链接里的doxys.exe是debug版本,还有个配置文件,感兴趣的朋友可以打开链接下载,按照下面的方法使用即可。
一、更改配置
:打开DoxySfile,设置INPUT(源码路径)、OUTPUT_DIRECTORY(输出路径)、OUTPUT_LANGUAGE(语言选择----界面语言)

如果是中文界面,只要改变INPUTOUT_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)





posted on 2010-04-25 22:04 Benjamin 阅读(1220) 评论(0)  编辑 收藏 引用 所属分类: 杂谈


只有注册用户登录后才能发表评论。
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理