基於Doxygen的C/C++注釋原則

基於Doxygen的C/C++注釋原則
標注總述
1.文件頭標注
2. 命名空間標注
3. 類、結構、枚舉標注
4. 函數注釋原則
5. 變量注釋
6. 模塊標注
7. 分組標注

總述
華麗的分隔線
//---------------------------------------------------------------------------
// 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__
1. 文件頭的標注
/*****************************************************************************
*  OpenST Basic tool library                                                 *
*  Copyright (C) 2014 Henry.Wen  [e-mail].                         *
*                                                                            *
*  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    [e-mail]                                              *
*  @version  1.0.0.1(版本號)                                                  *
*  @date     [e-mail]                                              *
*  @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                     *
*----------------------------------------------------------------------------*
*                                                                            *
*****************************************************************************/

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

3. 類、結構、枚舉標注
    /**
    * @brief 類的簡單概述 \n(換行)
    * 類的詳細概述
    */
    class Example
    {
    };
    
    枚舉類型定義、結構體類型定義注釋風格類似
    /** 
    * @brief 簡要說明文字 
    */
    typedef struct 結構體名字
    {
       成員1, /*!< 簡要說明文字 */ or ///<說明， /**<說明 */ 如果不加<，則會認為是成員2的注釋
       成員2, /*!< 簡要說明文字 */ or ///<說明， /**<說明 */ 
       成員3, /*!< 簡要說明文字 */ or ///<說明， /**<說明 */ 
    }結構體別名；

4. 函數注釋原則
    /** 
    * @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); 5. 變量注釋 /// 簡述
    /** 詳細描述. */ 或者 //! 簡述 //! 詳細描述 //! 從這里開始
    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的簡述消失 6. 模塊標注 模塊定義格式: /** * @defgroup 模塊名 頁的標題名 (模塊名只能英文,這個可以隨便取.在一個源文件里不能相同) * @{ (跟c語言{一樣起作用域功能) */ … 定義的內容 … /** @} */ 例： /** * @defgroup HenryWen Example.cpp * @{ */ … 定義的內容 … /** @} */
    
7. 分組標注 分組定義格式： /** * @name 分組說明文字 * @{ */ … 定義的內容 … /** @} */ 例： /** * @name PI常量 * @{ */
            #define PI 3.1415926737
            /** @} */
            
            /** * @name 數組固定長度常量 * @{ */
            const int g_ARRAY_MAX = 1024; /** @} */