C/C++註釋規範

Doxygen是一種開源跨平臺的，以相似JavaDoc風格描述的文檔系統，徹底支持C、C++、Java、Objective-C和IDL語言，部分支持PHP、C#。鑑於Doxygen良好的註釋風格，故基於Doxygen以造成本身的註釋規範。

1.標註總述

//-------------------------------------------------------------------
// Platform Defines
//-------------------------------------------------------------------
enum
{
    OST_PLATFORM_WIN32         = 1,
    OST_PLATFORM_LINUX_X86     = 2,
    OST_PLATFORM_LINUX_ARM     = 3,
    OST_PLATFORM_ANDROID       = 4,
    OST_PLATFORM_MACOSX        = 5,
};

//-------------------------------------------------------------------
// API Export/Import Macros
//-------------------------------------------------------------------
/** Indicates an exported and imported shared library function. */
#define OST_API_EXPORT        __declspec(dllexport)
#define OST_API_IMPORT        __declspec(dllimport)

//-------------------------------------------------------------------
// Digital Image Macros
//-------------------------------------------------------------------
#define OST_PI                        3.141592653589793f
#define OST_RGB2GRAY(r, g, b)        ( ((b) * 117 + (g) * 601 + (r) * 306) >> 10 )

//-------------------------------------------------------------------
// date and time at compile time
//-------------------------------------------------------------------
#define OST_TIMESTAMP                __DATE__ " " __TIME__

    2. 文件頭的標註  

/*****************************************************************************
*  OpenST Basic tool library                                                 *
*  Copyright (C) 2014 Henry.Wen  renhuabest@163.com.                         *
*                                                                            *
*  This file is part of OST.                                                 *
*                                                                            *
*  This program is free software; you can redistribute it and/or modify      *
*  it under the terms of the GNU General Public License version 3 as         *
*  published by the Free Software Foundation.                                *
*                                                                            *
*  You should have received a copy of the GNU General Public License         *
*  along with OST. If not, see <http://www.gnu.org/licenses/>.               *
*                                                                            *
*  Unless required by applicable law or agreed to in writing, software       *
*  distributed under the License is distributed on an "AS IS" BASIS,         *
*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  *
*  See the License for the specific language governing permissions and       *
*  limitations under the License.                                            *
*                                                                            *
*  @file     Example.h                                                       *
*  @brief    對文件的簡述                                                    *
*  Details.                                                                  *
*                                                                            *
*  @author   Henry.Wen                                                       *
*  @email    renhuabest@163.com                                              *
*  @version  1.0.0.1(版本號)                                                 *
*  @date     renhuabest@163.com                                              *
*  @license  GNU General Public License (GPL)                                *
*                                                                            *
*----------------------------------------------------------------------------*
*  Remark         : Description                                              *
*----------------------------------------------------------------------------*
*  Change History :                                                          *
*  <Date>     | <Version> | <Author>       | <Description>                   *
*----------------------------------------------------------------------------*
*  2014/01/24 | 1.0.0.1   | Henry.Wen      | Create file                     *
*----------------------------------------------------------------------------*
*                                                                            *
*****************************************************************************/

  3.命名空間

/**
 * @brief 命名空間的簡單概述 \n(換行)
 * 命名空間的詳細概述
 */
namespace OST
 {
 }

  4. 類、結構、枚舉標註

/**
 * @brief 類的簡單概述 \n(換行)
 * 類的詳細概述
 */
class Example
 {
 };

枚舉類型定義、結構體類型定義註釋風格相似

/** 
 * @brief 簡要說明文字 
 */
typedef struct 結構體名字
 {
      成員1, /*!< 簡要說明文字 */ or ///<說明， /**<說明 */
      成員2, /*!< 簡要說明文字 */ or ///<說明， /**<說明 */ 
      成員3, /*!< 簡要說明文字 */ or ///<說明， /**<說明 */ 
 }結構體別名;

  5. 函數註釋原則  

/** 
 * @brief 函數簡要說明-測試函數
 * @param index    參數1
 * @param t        參數2 @see CTest
 *
 * @return 返回說明
 *     -<em>false</em> fail
 *     -<em>true</em> succeed
 */
bool Test(int index, const CTest& t);

note：指定函數注意項事或重要的註解指令操做符 note格式以下： @note 簡要說明   retval：指定函數返回值說明指令操做符。(注:更前面的return有點不一樣.這裏是返回值說明) retval格式以下： @retval 返回值 簡要說明   pre：指定函數前置條件指令操做符 pre格式以下： @pre 簡要說明   par：指定擴展性說明指令操做符講。（它通常跟code、endcode一塊兒使用 ） par格式以下： @par 擴展名字   code、endcode：指定 code、endcode格式以下： @code 簡要說明(內容) @endcode   see：指定參考信息。 see格式以下： @see 簡要參考內容   deprecated：指定函數過期指令操做符。 deprecated格式以下： @deprecated 簡要說明 調試Bug說明 解決的bug說明，@bug 警告說明 (warning) 定義一些關於這個函數必須知道的事情，@warning 備註說明 (remarks) 定義一些關於這個函數的備註信息，@remarks 將要完成的工做 (todo) 說明哪些事情將在不久之後完成，@todo 使用例子說明 (example) 例子說明，@example example.cpp

/**
* @brief 打開文件 \n
* 文件打開成功後，必須使用::CloseFile函數關閉
* @param[in] fileName    文件名
* @param[in] fileMode    文件模式，能夠由如下幾個模塊組合而成：
*     -r讀取
*     -w 可寫
*     -a 添加
*     -t 文本模式(不能與b聯用)
*     -b 二進制模式(不能與t聯用)
* @return 返回文件編號
*  --1表示打開文件失敗(生成時:.-1)
* @note文件打開成功後，必須使用::CloseFile函數關閉
* @par 示例:
* @code
*        //用文本只讀方式打開文件
*        int ret = OpenFile("test.txt", "a");
* @endcode
* @see 函數::ReadFile::CloseFile (「::」是指定有鏈接功能,能夠看文檔裏的CloseFile變成綠,點擊它能夠跳轉到CloseFile.)
* @deprecated因爲特殊的緣由，這個函數可能會在未來的版本中取消
*/
int OpenFile(const char* fileName, const char* fileMode);

/**
* @brief 關閉文件
* @param [in] file    文件
*
* @retval 0     成功
* @retval -1    失敗
* @pre file 必須使用OpenFile的返回值
*/                
int CloseFile(int file);

-：生成一個黑心圓. -#：指定按順序標記。 ::：指定鏈接函數功能。（注：空格和「:」有鏈接功能,但建議仍是使用」::」。只對函數有用。） 它們格式以下: (-和::例子前面有了,就介紹-#例子。) - 簡要說明 -# 簡要說明 ::函數名 例：

/**
* @param [in] person 只能輸入如下參數：
* -# a:表明張三        // 生成 1. a:表明張三
* -# b:表明李四        // 生成 2. b:表明李四
* -# c:表明王二        // 生成 3. c:表明王二
*/
void GetPerson(int p);

  6. 變量註釋

/// 簡述
/** 詳細描述. */

或者

//! 簡述
//! 詳細描述
//! 從這裏開始
int m_variable_1; ///< 成員變量m_variable_1說明
int m_variable_2; ///< 成員變量m_variable_1說明
    
/**
* @brief 成員變量m_c簡要說明
*
* 成員變量m_variable_3的詳細說明，這裏能夠對變量進行
* 詳細的說明和描述，具體方法和函數的標註是同樣的
*/
bool m_variable_3;

若是變量須要詳細說明的可已按照m_varibale_3的寫法寫，注意，m_variable_2和m_variable_3之間必定須要空行，不然會致使m_variable_2的簡述消失   7. 模塊標註 模塊定義格式:

/**
* @defgroup 模塊名  頁的標題名 (模塊名只能英文,這個能夠隨便取.在一個源文件裏不能相同)
* @{ (跟c語言{同樣起做用域功能)
*/
… 定義的內容 …
/** @} */

例：

/**
* @defgroup HenryWen Example.cpp
* @{
*/
  … 定義的內容 …
/** @} */

  8. 分組標註 分組定義格式：

/**
* @name 分組說明文字
* @{
*/
… 定義的內容 …
/** @} */

例：

/**
* @name PI常量
* @{
*/
#define PI 3.1415926737
/** @} */

/**
* @name 數組固定長度常量
* @{
*/
const int g_ARRAY_MAX = 1024;
/** @} */