欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

Doxygen 常用指令以及C++注释风格

程序员文章站 2022-03-16 20:56:06
...

        在注释中加一些Doxygen支持的指令,主要作用是控制输出文档的排版格式,使用这些指令时需要在前面加上“\”或者“@”(JavaDoc风格)符号,告诉Doxygen这些是一些特殊的指令,通过加入这些指令以及配备相应的文字,可以生成更加丰富的文档,下面对比较常用的指令做一下简单介绍。

@file

档案的批注说明。

@author

作者的信息

@brief

用于class 或function的简易说明

eg:

@brief 本函数负责打印错误信息串

@param

主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明

@return

描述该函数的返回值情况

eg:

@return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE

@retval

描述返回值类型

eg:

@retval NULL 空字符串。
@retval !NULL 非空字符串。

@note

注解

@attention

注意

@warning

警告信息

@enum

引用了某个枚举,Doxygen会在该枚举处产生一个链接

eg:

@enum CTest::MyEnum

@var

引用了某个变量,Doxygen会在该枚举处产生一个链接

eg:

@var CTest::m_FileKey

@class

引用某个类,

格式:@class <name> [<header-file>] [<header-name>]

eg:

@class CTest "inc/class.h"

@exception

可能产生的异常描述

eg:

@exception 本函数执行可能会产生超出范围的异常

 

下面介绍C++的标注写法,c++不推荐c语言式的/* */风格注释,这里,除了文件头使用这种注释外其余到使用C++风格的注释。

【文件头】

/*!
* \file Ctext.h
* \brief 概述 
* 
*详细概述 
* 
* \author 作者名字
* \version 版本号(maj.min,主版本.分版本格式) 
* \date 日期 
*/

【命名空间】

/// \brief 命名空间的简单概述 
/// 
///命名空间的详细概述
namespace text
{
 ……
}

【类说明】

/// \brief Ctext的doxygen测试
///
/// 作doxygen测试用
class Ctext
{
}

【函数标注】

/// \brief 函数简要说明-测试函数
/// \param n1 参数1
/// \param c2 参数2
/// \return 返回说明
bool text(int n1,Ctext c2);
/// \brief 函数简要说明-测试函数
/// 
/// 函数详细说明,这里写函数的详细说明信息,说明可以换行
/// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行
/// ,详细说明之前不需要任何标识符
/// \param n1 参数1说明
/// \param c2 参数2说明
/// \return 返回说明
/// \see text
bool text2(int n1,Ctext c2);

【变量及枚举】

    int m_a;     ///< 成员变量1m_a说明
    double m_b; ///< 成员变量2m_b说明
 
 
    /// \brief 成员变量m_c简要说明
    ///
    /// 成员变量m_c的详细说明,这里可以对变量进行
    ///详细的说明和描述,具体方法和函数的标注是一样的
    float m_c;
 
 
    /// \brief xxx枚举变量的简要说明
    ///
    /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明
    ///的写法是一致的。每个枚举变量下可以进行单独说明
    enum{
        em_1,///< 枚举值1的说明
        em_2,///< 枚举值2的说明
        em_3 ///< 枚举值3的说明
    };