doxygen注释生成api文档(一)

doxygen注释生成api文档

项目注释

注释的基本结构如下：

/**
 * @mainpage 项目名称
 * @section 目录一
 *  手动阀手动阀
 * @section 目录二
 * 发士大夫s
 * -# sdf
 * -# sdfsdfa
 * @section 目录三
 * @section 目录四
 * <table>
 * <tr><th>你好 <td>hello
 * <tr><th>哈喽 <td>hi
 * <tr><th>再见 <td>
 * -# bye
 * -# seeyou
 * -# goodbye
 * </tr>
 * </table>
 */

再经过doxygen编译后生成的页面如下：

文件注释

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @author 作者
 * @version 版本号
 * @date 年-月-日
 * @copyright 版权
 */

/**
 * @file pool_manger.h
 * @attention
 * sdflasdlfkasjdlfkasjd;fk
 * @par 修改日志
 * <table>
 * <tr><th>Data   <th>Version  <th>Author  <th>Desc
 * <tr><td>xxxx   <td>V1.0     <td>yyx     <th>
 * </table>
 */

结构体注释

/**
 * @brief MixMemory对象池中管理对象的最小单元
 * @struct MixMemoryUnit
 */
typedef struct MixMemoryUnit{
    
    
    MixMemory* ptr = nullptr; /*!< 混合内存对象指针*/
    size_t size = 0;          /*!< 内存大小*/
    bool available = false;   /*!< 当前内存是否可以分配*/
    bool isShare = false;     /*!< 当前内存是否为共享内存*/
    int id = -1;
}MixMemoryUnit;

枚举类型注释

/**
 * @brief 头信息的枚举类型
 * @enum DataHead
 */
enum class DataHead:char{
    
    
    INIT,         /*!< 初始化状态*/
    GPU,          /*!< GPU内存*/
    CPU,          /*!< CPU内存*/
    SHARE         /*!< 共享内存*/
};

函数的注释

/** 拷贝构造函数
         * @param[in] tensor对象
         * @warning 传入参数不能为空
         * @note 构造一个tensor对象
         * @par 示例:
         * @code
            extern  IThread *pThread;
            HANDLE hEvent = pThread->GetEventHandle();
            while(WaitForSingleObject(hEvent,0) != WAIT_OBJECT_0){
                //Do something
            }
         * @endcode
         */
        tensor(const tensor& other);

关联注释

下面这个运算符重载函数不属于tensor类，但是要把它放在tensor的说明文档中

/**
 * @relates tensor
 */
inline std::ostream& operator<< (std::ostream& ost, tensor& t) {
    
    
    ost << t.descriptor_string() ;
    return ost;
}

常量、变量注释

//定义一个整型变量a
int a;

/**
 * @brief 定义一个整型变量a
*/
int a;

int a; /*!< 定义一个整型变量a */
int a; /**< 定义一个整型变量a */
int a; //!< 定义一个整型变量a
int a; ///< 定义一个整型变量a

常用注释命令

1.@author       作者信息

2.@brief        简要说明概要信息

3.@bug          被标记的代码会在Bug列表中出现

4.@class        对类进行标注

5.@data         日期

6.@file         文件名

7.@param        主要用于函数说明，对参数进行说明

8.@return       描述函数的返回值情况

9.@retval       描述函数返回值类型

10.@note        注解

11.@attention   注意

12.@name        分组名

13.@warning     警告信息

14.@enum        引入了某个枚举

15.@var         引入了某个变量

16.@exception   可能产生的异常描述

17.@todo        对将要做的事情进行注释

18.@see         一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接

19.@relates     通常用做把非成员函数的注释文档包含在类的说明文档中

20.@since       从哪个版本后开始有这个函数的

21.@code        在注释中开始说明一段代码，直到@endcode结束

22.@endcode     在注释中代码段的结束

23.@remarks     备注

24.@pre         说明代码项的前提条件

25.@post        说明代码项之后的使用条件

26.@deprecated  这个函数可能会在将来的版本中取消

27.@defgroup    模块名

   @{
    
               模块开始

   @}           模块结束

28.@version     版本号

29.@par         开始一个段落

30.@detail      详细描述