基於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 [email protected]. *
* *
* 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 [email protected] *
* @version 1.0.0.1(版本號) *
* @date [email protected] *
* @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;
/** @} */用///<注釋符代替/**<注釋符。///<後面的注釋會直接在結構體變量後面顯示。
小弟不敢自诩是高手，不過一點經驗而已。其實Doxygen工具非常棒，其實它是可以提取出cpp文件中的注釋的。
具體方法是在cpp代碼中加入符合Doxygen規定的注釋，例如：
/** @defgroup FileUtils ...函數
* @{
*/
/** 函數名 Test \n
* @param 無
* @return
* @note 若超過試用期，系統應該提示並退出\n
* 1
* 2
* 3
* ... ...
* 修改日志：
* 1 V1.0.0
* 2 V2.0.0
* ... ...
* @par 示例:
* @code
// 調用樣例
bool blnRet = Test();
* @endcode
* @see
* @deprecated
*/
bool CMapApp::Test()
{
/**
* 1
* －1.1
* －1.2
* －1.3
*/
C++ code ... ...
/**
* 2
*/
C++ code ... ...
......
/**
* 6
*/
... ...
}
/** @}*/
/** @}*/
