编程规范 - doxygen注释规范示例(C++)
doxygen注释规范示例(C++)
doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写。下面是我总结的c/c++的注释书写规范,代码风格结合了google c++风格。
/** | 文件注释 * @file apply.c | “@file”后的文件名需与当前文件名一致 * @author clover/[email protected] * @version 1.0 * @date 2013-12-12 * @brief 概述:doxygen使用文档 * 详细介绍了doxygen的C++注释方法 * @details 详细说明 * @see MainWindow参考其它的相关的函数,这里作一个链接 url * @note 描述需要注意的问题 */ /// This macro is toolong, so comment here briefly! | 推荐使用简洁的宏注释 #define HTTP_REQUEST_LEN_MAX APPLY_BUF_SIZE_BIG /** * The detail macro comment, may be multi-line. | 尽量少写宏函数,可以使用内联函数代替 * @param a The brief parameter comment * @param b The brief parameter comment * @return The brief return value comment */ #define MAX(a, b) ((a) > (b))? (a) : (b) /** * @brief 结构体 | 结构体成员的详细注释写在该成员上面 * (与名称后面的描述有一个就可以) | 结构体成员的详细注释与上一成员间留1个空行 * | 推荐使用简洁的结构体注释 */ struct StructVariable { /// @brief 简单的描述 | “///”与注释间留有2个空格 int a; ///< variable a | “///<”与注释间留有1个空格 int b; ///< variable b /** this is details mement comment */ int c; ///< variable c int d; ///< variable d }; /** * @enum 性别枚举 */ enum Sex { /// @enum 性别枚举 kMale, ///< enum male kFemale ///< enum female }; /** * @brief 主窗口 */ class MainWindow : public QMainWindow { Q_OBJECT public: MainWindow(QWidget *parent = 0); ~MainWindow(); bool SetProName(QString name); ///< 设置工区名称 private: QString m_name_; }; /// @brief 函数名称:setProName static int ApplyLogin(); /** * @brief 函数名称:setProName |尽量避免函数声明和定义重复注释 * @todo 代码实现的功能: 设置工区名称 * @param 参数:QWidget* * @return 说明:int * @retval 1. true 名字设置成功 (返回值说明(可选)) * @retval 2. false 名字设置失败 * @bug 此处的bug描述: 无 */ bool MainWindow::SetProName(QString name) { } // 其它注释 // 代码中其余注释一律使用普通的单行注释“//”和多行注释“/*”“*/ /* * Doxygen 会忽略你注释中的换行符,将多行注释连接成一个连续行并使用空格隔开。 * 如果你希望保留两行注释之间的换行,需要在该行末加入“/n”。 * * 常用命令 * @attention 注意 * @author 作者 * @bug 缺陷,链接到所有缺陷汇总的缺陷列表 * @brief 简要注释 * @code 代码块开始,与“endcode”成对使用 * @endcode 代码块结束,与“code”成对使用 * @details 详细注释 * @date 日期 * @file < 文件名> 文件参考,用在文件注释中 * @param 参数,用在函数注释中 * @return 返回,用在函数注释中 * @todo TODO,链接到所有TODO 汇总的TODO 列表 * @version 版本 * @warning 警告 */
相关推荐
liconstantine 2013-06-15