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

系统管理员 2022-04-10 01:14 402阅读 0赞

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

<table> 
 <tbody> 
 <tr> 
 <td style="vertical-align:top;"> @file </td> 
 <td style="vertical-align:top;"> 档案的批注说明。 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @author </td> 
 <td style="vertical-align:top;"> 作者的信息 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @brief </td> 
 <td style="vertical-align:top;"> 用于class&nbsp;或function的简易说明 eg： <code>@brief&nbsp;</code><code>本函数负责打印错误信息串</code> </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @param </td> 
 <td style="vertical-align:top;"> 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @return </td> 
 <td style="vertical-align:top;"> 描述该函数的返回值情况 eg: @return&nbsp;本函数返回执行结果，若成功则返回TRUE，否则返回FLASE </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @retval </td> 
 <td style="vertical-align:top;"> 描述返回值类型 eg: <code>@retval NULL&nbsp;</code><code>空字符串。</code> <code>@retval !NULL&nbsp;</code><code>非空字符串。</code> </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @<a rel="nofollow">note</a> </td> 
 <td style="vertical-align:top;"> 注解 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @attention </td> 
 <td style="vertical-align:top;"> 注意 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @warning </td> 
 <td style="vertical-align:top;"> 警告信息 </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @enum </td> 
 <td style="vertical-align:top;"> 引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg： @enum CTest::MyEnum </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @var </td> 
 <td style="vertical-align:top;"> 引用了某个变量，Doxygen会在该枚举处产生一个链接 eg： @var CTest::m_FileKey </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @class </td> 
 <td style="vertical-align:top;"> 引用某个类， 格式：@class &lt;name&gt; [&lt;header-file&gt;] [&lt;header-name&gt;] eg: @class CTest "inc/class.h" </td> 
 </tr> 
 <tr> 
 <td style="vertical-align:top;"> @exception </td> 
 <td style="vertical-align:top;"> 可能产生的异常描述 eg: @exception&nbsp;本函数执行可能会产生超出范围的异常 </td> 
 </tr> 
 </tbody> 
</table>

下面介绍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的说明
 };

其他参考文章：

[https://blog.csdn.net/wenrenhua08/article/details/39591239][https_blog.csdn.net_wenrenhua08_article_details_39591239]

[https_blog.csdn.net_wenrenhua08_article_details_39591239]: https://blog.csdn.net/wenrenhua08/article/details/39591239