語法簡介

Doxygen 是一個程序的文件產生工具，可將程序中的特定批注轉換成為說明文件。提供了一套注釋方式便于把代碼中的注釋生成說明文檔。
很多開源項目都在使用，例如：

• wxWidgets
• clang

下面是常用的注釋簡介。

1. 簡單注釋

• 單行注釋：///或者//!
• 多行注釋：/**或者/*!

2. 文件注釋

文件注釋通常放在整個文件開頭。

/**
 * @file 文件名
 * @brief 簡介
 * @details 細節
 * @mainpage 工程概覽
 * @author 作者
 * @email 郵箱
 * @version 版本號
 * @date 年-月-日
 * @license 版權
 */

例如：

/**
 * @file Test.h
 * @brief 測試頭文件
 * @details 這個是測試Doxygen
 * @mainpage 工程概覽
 * @author jdzhangxin
 * @email jdzhangxin@126.com
 * @version 1.0.0
 * @date 2017-11-17
 */

生成文檔效果

3. 類定義注釋

類定義的注釋方式非常簡單，使用@brief后面填寫類的概述，換行填寫類的詳細信息。

 /**
 * @brief 類的簡單概述
 * 類的詳細概述
 */

例如：

 /**
 * @brief 測試類
 * 主要用來演示Doxygen類的注釋方式
 */
 class Test{
 };

生成文檔效果

命名空間、結構體、聯合體、枚舉定義與類定義注釋方式一致。

4. 常量/變量的注釋

常量/變量包括以下幾種類型

• 全局常量變量
• 宏定義
• 類/結構體/聯合體的成員變量
• 枚舉類型的成員

注釋分為兩種方式，可根據具體情況自行選擇

• 代碼前注釋

  /// 注釋
  常量/變量
  

  例如：

  /// 緩存大小
  #define BUFSIZ 1024*4
  

• 代碼后注釋

  常量/變量 ///< 注釋
  

  例如：

  #define BUFSIZ 1024*4 ///< 緩存大小
  

  生成文檔效果

5. 函數注釋

• 簡約注釋
  函數注釋主要包含函數簡介(@brief)、參數說明('@param')、返回說明(@return)和返回值說明(@retval)四部分。

  /**
   * @brief 函數簡介
   *
   * @param 形參 參數說明
   * @param 形參 參數說明
   * @return 返回說明
   *   @retval 返回值說明
   */
  

• 詳細注釋
  可以根據需要添加詳細說明(@detail)、注解(@note)、注意(@attention)、警告(@warning)或者異常(@exception)等。

  /**
   * @brief 函數簡介
   * @detail 詳細說明
   * 
   * @param 形參 參數說明
   * @param 形參 參數說明
   * @return 返回說明
   *   @retval 返回值說明
   * @note 注解
   * @attention 注意
   * @warning 警告
   * @exception 異常
   */
  

• 例子
  以main()函數為例添加函數注釋。

  /**
  * @brief 主函數
  * @details 程序唯一入口
  *
  * @param argc 命令參數個數
  * @param argv 命令參數指針數組
  * @return 程序執行成功與否
  *     @retval 0 程序執行成功
  *     @retval 1 程序執行失敗
  * @note 這里只是一個簡單的例子
  */
  int main(int argc, char* argv[])
  

  生成文檔效果

其他

下面一些標注方式可以根據需要選擇使用。