doxygen的使用（二）給代碼添加javadoc風格的註釋

原創文章，歡迎閱讀，禁止轉載。

本文記一下javadoc風格註釋的寫法，這些特殊格式的註釋稱做標籤。按照這種規範寫的註釋才能生成到文檔中。

塊註釋的寫法

/**
 * @brief 這個塊註釋
 * doxygen標籤就是寫在這裏(除了單行註釋)
 * 格式爲雙星開始"/** ... */"，標籤能夠寫多行
 */

單行註釋的寫法

int var; ///< 用"///<"的是單行註釋
int abc; ///< 經常使用於全局變量、成員變量、結構體成員、枚舉值等

（標籤用'@'和'\'開頭都是能夠的）
C++經常使用的標籤有：
@file 要文檔化的文件，這個必須寫，不然文件中的所有忽略
@author 做者
@date 日期
@brief 功能或行爲描述，能夠多行
@param 參數
@param[out] 輸出參數
@param[in] 輸入參數
@return 返回說明
@retval 返回值具體說明
@note 備註
@see 相關項(貌似不能寫typedef的函數指針)
@todo 待辦事項

一些高級的標籤
@mainpage 標識本文會顯示在手冊主頁上，在該段中寫各類html代碼便可

這是我寫的註釋的例子(export.h)

/**
 * @file export.h 
 * @author zhaojk
 * @brief 註釋標註，試試自動生成文檔的效果
 * @version 0.1
 * @note 其中file標籤必須寫
 * @todo 看幫助手冊，給個人手冊作個主頁
 */

/**
 * @brief 回調參數原型
 */
typedef void(EventCallBack*)(int event,void* param);

/**
 * @brief 事件ID類型
 */
typedef int EVENTID;

/**
 * @struct 用戶信息
 */
typedef struct  
{
    char ip[16];    ///< IP地址
    int port;        ///< 端口號
}Adddess;

/**
 * @enum
 */
enum EmDeviceType
{
    Device_28181=0,    ///< 28181設備
    Device_sip,        ///< sip設備
    Device_onvif,    ///< onvif設備
    Device_other    //沒按規範註釋就不會出如今手冊
};

void* g_Instance; ///<全局實例

/**
 * @brief 設置事件回調
 * @param cbFun 事件回調函數
 * @param cbParam 用戶參數
 * @return 返回操做結果
 * @retval true成功，false失敗
 * @see EventCallBack
 */
bool SetCallBack(EventCallBack cbFun,void* cbParam);


/**
 * @brief 獲取版本號
 * @param[out] version 返回的版本號
 */
void GetVersion(char version[128]);

/**
 * @brief 打開數據庫
 * @param dbname 數據庫名稱
 * @param username 用戶名
 * @param passwd 密碼
 * @return 返回錯誤碼
 * @see CloseDB
 */
int OpenDB(char* dbname,char* username,char* passwd);

/**
 * @brief 關閉數據庫
 * @return void
 * @see EmDeviceType
 */
void CloseDB();

 

再來一個手冊主頁的例子(mainpage.h)

/**
 * @mainpage 這是主頁
 * @brief 這是本手冊的主頁<br>這是第二行
 * @author zhaojk
 */

 

瞭解更多
經常使用標籤的使用，請看doxygen的參考手冊，也能夠看一下開源庫。
更多更高級的標籤，請看參考手冊
貌似對html格式和md格式有支持。

原創文章，歡迎閱讀，禁止轉載。