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

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

一、  C++风格的注释

1   概述

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

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

2     简述与详述

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

（1）使用 \brief 参数标识，空行作为简述和详述的间隔标识

        ///    \brief   Brief description. 

///    description continued.  

///  

///    Detailed description starts here.  

///

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

///    Briefdescription  

///   description continued.  

///     

///    Detaileddescription starts here.

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

///         Brief description  

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

///         Detailed description starts here.  

///

3    注释风格约定

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

4 文件头注释示例  // 

///    COPYRIGHT NOTICE  

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

///    All rights reserved.  

///  

///@file            （本文件的文件名eg：Test.h） 

/// @brief           （本文件实现的功能的简述） 

///  

///（本文件实现的功能的详述）  

///  

/// @version1.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,constchar *s);  

8    枚举变量的注释示例

///    颜色的枚举定义  

///   

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

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

enumTEnum  

{  

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

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

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

}enumVar;     

9     需要注意的问题

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

 

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

1 准备工作

制作文档前，我们要完成以下准备工作：

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

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

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

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

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

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

3 填写参数

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

 

3.1 Project页（如上图所示）   

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

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

3.2  Messages页

 

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

3.3  Input页

  

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

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

3.4 Source Browser页

 

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

3.2.5 Html页

 

选择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

 

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

4    Doxygen使用的常见问题小结

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

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

保存方法为：

用vs打开.h，.cxx文件，文件->Advanced SavedOptions…->Encoding，选择Codepage 20936。如下两图所示：

 

 

 

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

解决：首先确保安装了graphviz forwin，注意不是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 HelpWorkshop获得。

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

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

例如：

class __declspec(dllexport) CClassName:publicCObject

{

}

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