Doxygen的注释风格

港控/mmm° 2022-09-18 01:46 198阅读 0赞

# Doxygen的注释风格 #

## from: [http://ticktick.blog.51cto.com/823160/188674][http_ticktick.blog.51cto.com_823160_188674] ##

## 5.1 综述 ##

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是 *brief*描述, 另一种就是 *detailed*。 两种都是可选的，但不能同时没有。

顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。

Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以介绍。

若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：  
1） 文件头（包括.h和.cpp）  
主要用于声明版权，描述本文件实现的功能，以及文件版本信息等  
2） 类的定义  
主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述  
3） 类的成员变量定义  
在类的成员变量上方，对该成员变量进行简要地描述  
4） 类的成员函数定义  
在类定义的成员函数上方，对该成员函数功能进行简要描述  
5） 函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

## 5.2 Doxygen支持的指令 ##

### 5.2.1 概述 ###

可以在注释中加一些Doxygen支持的指令， 主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

### 5.2.2 常用指令介绍 ###

<table> 
 <tbody> 
  <tr> 
   <td> 
    <div>
      @file 
    </div> </td> 
   <td> 
    <div>
      档案的批注说明。 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @author 
    </div> </td> 
   <td> 
    <div>
      作者的信息 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @brief 
    </div> </td> 
   <td> 
    <div>
      用于class&nbsp;或function的简易说明 
    </div> 
    <div>
      eg： 
    </div> 
    <div> 
     <code>@brief&nbsp;</code> 
     <code>本函数负责打印错误信息串</code> 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @param 
    </div> </td> 
   <td> 
    <div>
      主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @return 
    </div> </td> 
   <td> 
    <div>
      描述该函数的返回值情况 
    </div> 
    <div>
      eg: 
    </div> 
    <div>
      @return&nbsp;本函数返回执行结果，若成功则返回TRUE，否则返回FLASE 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @retval 
    </div> </td> 
   <td> 
    <div>
      描述返回值类型 
    </div> 
    <div>
      eg: 
    </div> 
    <div> 
     <code>@retval NULL&nbsp;</code> 
     <code>空字符串。</code> 
     <br> 
     <code>@retval !NULL&nbsp;</code> 
     <code>非空字符串。</code> 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @ 
     <a rel="nofollow">note</a> 
    </div> </td> 
   <td> 
    <div>
      注解 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div> 
     <strong>@attention</strong> 
    </div> </td> 
   <td> 
    <div>
      注意 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @warning 
    </div> </td> 
   <td> 
    <div>
      警告信息 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @enum 
    </div> </td> 
   <td> 
    <div>
      引用了某个枚举，Doxygen会在该枚举处产生一个链接 
    </div> 
    <div>
      eg： 
    </div> 
    <div>
      @enum CTest::MyEnum 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @var 
    </div> </td> 
   <td> 
    <div>
      引用了某个变量，Doxygen会在该枚举处产生一个链接 
    </div> 
    <div>
      eg： 
    </div> 
    <div>
      @var CTest::m_FileKey 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @class 
    </div> </td> 
   <td> 
    <div>
      引用某个类， 
    </div> 
    <div>
      格式：@class &lt;name&gt; [&lt;header-file&gt;] [&lt;header-name&gt;] 
    </div> 
    <div>
      eg: 
    </div> 
    <div>
      @class CTest "inc/class.h" 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div>
      @exception 
    </div> </td> 
   <td> 
    <div>
      可能产生的异常描述 
    </div> 
    <div>
      eg: 
    </div> 
    <div>
      @exception&nbsp;本函数执行可能会产生超出范围的异常 
    </div> </td> 
  </tr> 
 </tbody> 
</table>

## 5.3 JavaDoc风格的注释 ##

### 5.3.1 概述 ###

JavaDoc风格的注释风格主要使用下面这种样式： 即在注释块开始使用两个星号 ‘ \* ‘

/**   description       
         *    description       
         *    description       
         */

### 5.3.2 简述与详述的方式 ###

Doxygen支持的块（类、函数、结构体等）的注释描述分为两种：简述 和 详述

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

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

/*!    @brief  Brief description.   
        *    description continued.   
        *   
        *    Detailed description starts here.   
        */

2） 直接使用javaDoc风格，javaDoc风格自动以简述开头，以空行（或者小数点加空格）作为简述与详述的分割

/**    Brief description   
          *    description continued   
          *   
          *    Detailed description starts here.   
          */

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

### 5.3.3 文件头注释示例 ###

[![165640551.jpg][]][165640551.jpg]

### 5.3.4 类定义注释示例 ###

/**    本类的功能：打印错误信息   
        *    
        *     本类是一个单件   
        *     在程序中需要进行错误信息打印的地方   
        */  
       class CPrintError   
       {   
                   ……   
       }

### 5.3.5 类成员变量定义示例 ###

（1）在成员变量上面加注释的格式

/// 成员变量描述   
         int  m_Var;

（2）在成员变量后面加注释的格式

int  m_color;     /// 颜色变量

### 5.4.7 成员函数的注释示例 ###

/// 下面是一个含有两个参数的函数的注释说明（简述）    
       ///     
       ///     这里写该函数的详述信息     
       ///     @param a 被测试的变量（param描述参数）     
       ///     @param s 指向描述测试信息的字符串     
       ///     @return    测试结果 （return描述返回值）    
       ///     @see    Test()    （本函数参考其它的相关的函数，这里作一个链接）   
       ///     @note    (note描述需要注意的问题)     
       int testMe(int a,const char *s);

### 5.4.8 枚举变量的注释示例 ###

///    颜色的枚举定义   
       ///    
       ///    该枚举定义了系统中需要用到的颜色\n   
       ///    可以使用该枚举作为系统中颜色的标识   
       enum TEnum    
       {    
           RED,            ///< 枚举，标识红色        
           BLUE,           ///< 枚举，标志蓝色        
           YELLOW          ///< 枚举，标志黄色.        
       }enumVar;

## 5.5 需要注意的问题 ##

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

## 6 Doxygen使用的常见问题小结 ##

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

解决：在expert中的INPUT选项页的INPUT\_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。

### 6.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文件

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

例如：

class \_\_declspec(dllexport) CClassName:public CObject

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

[http_ticktick.blog.51cto.com_823160_188674]: http://ticktick.blog.51cto.com/823160/188674
[165640551.jpg]: /images/20220828/fbfdf871268f46f19cfc3431d38159a6.png