doxygen的使用给代码添加javadoc风格的注释

Posted 2020-08-14

原创文章，欢迎阅读，禁止转载。

本文记一下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格式有支持。

原创文章，欢迎阅读，禁止转载。