加载中…
个人资料
漠北
漠北
  • 博客等级:
  • 博客积分:0
  • 博客访问:298,208
  • 关注人气:33
  • 获赠金笔:0支
  • 赠出金笔:0支
  • 荣誉徽章:
相关博文
推荐博文
谁看过这篇博文
加载中…
正文 字体大小:

Doxygen C++注释规范及生成帮助文档配置步骤

(2012-03-20 14:25:08)
标签:

doxygen

c

注释规范

生成

帮助文档

配置

步骤

分类: programming

Doxygen C++注释规范及生成帮助文档配置步骤

一、  C++风格的注释

1    概述

C++的注释风格主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’

其他地方其实与JavaDoc的风格类似,只是C++风格不用 “*” 罢了。

2     简述与详述

C++风格的简述与详述方式与javaDoc类似。一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,C++风格可以使用的分隔方法有以下两种:

(1)使用 \brief 参数标识,空行作为简述和详述的间隔标识

         ///     \brief   Brief description.  

///     description continued.  

///  

///     Detailed description starts here.  

///

(2) 使用以空行(或者小数点加空格)作为简述与详述的分割

///    Brief description  

///    description continued.  

///      

///    Detailed description starts here.

以小数点加空格作为分隔如下:

///          Brief description  

///          description continued . (注意:这里有一个小数点,加上一个空格)  

///          Detailed description starts here.  

///

3    注释风格约定

1. 一个代码块(类、函数、结构等)的概述采用单行的”///”加一个空格开头的注释,并写在该代码块声明的前面;
    2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释,若不足两行第二行的开头也要写出来,并且放在代码块定义的前面;如果某代码没有声明只有定义或者相反,则在定义或者声明前面写上单行的概述+一个空行+多行的详述;
    3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释;
    4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释(相当于是给改变量一个概述);
    5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面;
    6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面;
    7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面;
    8. 文件头的版权以及文件描述的注释参见例代码。

文件头注释示例   //////////////////////////////////////////////////////////////////////////  

///     COPYRIGHT NOTICE  

///     Copyright (c) 2009, 华中科技大学      (版权声明)  

///     All rights reserved.  

///  

/// @file             (本文件的文件名eg:Test.h)  

/// @brief            (本文件实现的功能的简述)  

///  

///(本文件实现的功能的详述)  

///  

/// @version 1.1      (版本声明)  

/// @author           (作者,eg:卢俊)  

/// @date             (文件创建日期,eg:2009年7月15日)  

///  

///  

///     修订说明:最初版本  

//////////////////////////////////////////////////////////////////////////

5   类定义注释示例

///     本类的功能:打印错误信息  

///  

///     本类是一个单件  

///     在程序中需要进行错误信息打印的地方  

class CPrintError 

           …… 

6     类成员变量定义示例

(1)在成员变量上面加注释的格式

     /// 成员变量描述

int   m_Var;

(2)在成员变量后面加注释的格式

int   m_color;     /// 颜色变量   

7    成员函数的注释示例

/// 下面是一个含有两个参数的函数的注释说明(简述)   

///     

///      这里写该函数的详述信息     

///      @param a 被测试的变量(param描述参数)     

///      @param s 指向描述测试信息的字符串     

///      @return     测试结果(return描述返回值)   

///      @see     Test()     (本函数参考其它的相关的函数,这里作一个链接)  

///      @note     (note描述需要注意的问题)     

int testMe(int a,const char *s);  

   枚举变量的注释示例

///     颜色的枚举定义  

///   

///     该枚举定义了系统中需要用到的颜色\n  

///     可以使用该枚举作为系统中颜色的标识  

enum TEnum  

 

     RED,            ///< 枚举,标识红色        

     BLUE,           ///< 枚举,标志蓝色        

     YELLOW          ///< 枚举,标志黄色.        

}enumVar;     

9     需要注意的问题

(1)Doxygen会忽略你在注释中加入的多余的换行,如果你希望保留两行注释之间的空行,那么,在该行加入 \n

 

二、  Doxygen生成帮助文件配置步骤

1 准备工作

制作文档前,我们要完成以下准备工作:

安装Doxygen、Graphviz和“HTML Help Workshop”。我使用的HTML Help

Workshop版本是4.74.8702.0,英文版。网上有汉化版本,但运行时偶尔会出错。

2 打开Doxywizard之后,会出现下图所示的界面:

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

Doxy提供三种配置方式:Wizard方式为简化方式,可以配置一些简单的指标,其余的使用默认配置;Expert提供详细的配置;Load可以加载Doxyfile文件进行编辑。此处以Expert方式为例说明。

Doxyfile是Doxygen的配置文件,Doxygen就是根据本文件的配置生成帮助文档的。

可以直接点“Save...”按钮,将配置保存在本地某一路径下面,此处为doc\Doxyfile。这时,Doxyfile的内容是Doxygen的默认设置。Doxyfile是普通文本文件,我们可以直接打开编辑。不过在Doxywizard的界面上填写也很方便,每个参数都有详细提示。建议用Doxywizard完成第一次设置。以后如果需要调整个别参数,可以直接编辑Doxyfile。

3 填写参数

点“Expert...”按钮后,开始填写配置参数。

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

 

3.1  Project页(如上图所示)   

DOXYFILE_ENCODING是Doxyfile的文本编码。如果文件中有中文字符,可以填写GBK或者GB2312,此处我填写的是GB2312。

填写项目名(PROJECT_NAME)、项目版本(PROJECT_NUMBER)、输出目录(OUTPUT_DIRECTORY)和输出语言(OUTPUT_LANGUAGE)。输出目录可以按Doxyfile的相对目录填写。输出语言相当于程序资源,选择Chinese。

3.2  Messages

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

 

在Messages页将WARN_LOGFILE填写为build.log。这样,Doxygen会将编译时出现的警告和错误保存在build.log,我们可以对照修改。

3.3  Input

   Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

指定输入源文件目录(INPUT),可以点击“Select”按钮选择本地工程所在目录,然后点击“+”按钮,就添加到了红色标注区域。将输入文件编码(INPUT_ENCODING)改为GBK或者GB2312。

FILE_PATTERNS参数是Doxygen要处理的文件类型,缺省值包括Doxygen支持的所有文件类型。不能用Doxygen文档化任意文件类型。例如Doxygen不支持汇编程序。这里不做任何修改。

3.4 Source Browser

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

 

选择SOURCE_BROWSER,在文档中包含源代码。

3.2.5 Html

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

 

选择GENERATE_HTMLHELP后,Doxygen会准备生成chm文件需要的项目文件、目录文件和索引文件。

3.6  LaTex

取消GENERATE_LATEX,不产生LaTex输出。

3. 7  Dot

在Dot页,可以选上UML_LOOK、CALL_GRAPH和CALLER_GRAPH。CALL_GRAPH是本函数调用其它函数的示意图,例如:

 

CALLER_GRAPH是本函数调用者的示意图,例如:

 

3.8  运行Doxygen

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

 

就会在之前设定的./doc/目录下生成一个名为“html”的文件夹,其中就是帮助文档。

4     Doxygen使用的常见问题小结

4.1     中文问题:中文注释在文档中是乱码

解决:在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”,这样基于GB的文本编辑器生成的代码就可以正常使用了。对于使用vs编译器写的代码,需要将要生成帮助文档的.h,.cxx文件都保存为GB2312形式,否则运行Doxyzen时不能如愿生成中文帮助文档,会报出:Error: failed to translate characters from GB2312 to UTF-8: check INPUT_ENCODING错误信息。

保存方法为:

用vs打开.h,.cxx文件,文件->Advanced Saved Options…->Encoding,选择Codepage 20936。如下两图所示:

 

 
Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

Doxygen <wbr>C++注释规范及生成帮助文档配置步骤

 

4.2    图形问题:无法绘制类图协作图等图形。

解决:首先确保安装了graphviz for win,注意不是wingraphviz,后者是一个graphviz的com封装,但是doxygen并不是基于它开发的,所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。

如果出现无法包含.map文件的错误,可以将工作目录设置成html,并将html中所有文件都清除再试。这个问题的原因还不太确定。

6.3    输出chm的问题:如何输出.chm文件

配置时注意expert中的HTML页:选中“GENERATE_HTMLHELP”,然后在CHM_FILE中填上想要的chm文件名。

HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。

或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件,编译完成后即可在该html文件夹中找到对应的chm文件

4.4     Doxygen无法为DLL中定义的类 导出文档

例如:

class __declspec(dllexport) CClassName:public CObject

{

}

目前发现Doxygen无法识别出DLL中定义的类。

 

0

阅读 评论 收藏 转载 喜欢 打印举报/Report
  • 评论加载中,请稍候...
发评论

    发评论

    以上网友发言只代表其个人观点,不代表新浪网的观点或立场。

      

    新浪BLOG意见反馈留言板 电话:4000520066 提示音后按1键(按当地市话标准计费) 欢迎批评指正

    新浪简介 | About Sina | 广告服务 | 联系我们 | 招聘信息 | 网站律师 | SINA English | 会员注册 | 产品答疑

    新浪公司 版权所有