C++注释风格

综述

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的，但不能同时没有。

• 简述(brief)：在一行内简述地描述
• 详细描述(detailed description)：提供更长, 更详细的文档

Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以介绍。
若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：

• 文件头（包括.h和.cpp）
  • 主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
• 类的定义
  • 主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
• 类的成员变量定义
  • 在类的成员变量上方，对该成员变量进行简要地描述
• 类的成员函数定义
  • 在类定义的成员函数上方，对该成员函数功能进行简要描述
• 函数的实现
  • 在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明

C++注释风格

Doxygen 支持多种注释风格，比如 JavaDoc-like 风格，Qt 风格等。在写 C++ 代码时，我们应该遵守 C++ 的行注释风格，所谓行注释风格，是指一般 C++ 程序员避免使用 C 风格的注释符号 /* */，而是使用 3 个连续的 / 作为注释的开头。除了这个区别之外，其他部分和 JavaDoc 风格类似：

• 一个对象的 brief description 用单行的 /// 开始，并且写在代码前面。一般 brief 写在头文件中，对象的声明之前。

• 一个对象的 detailed description 用多于两行的 /// 开始，并且写在代码前面。如果注释长度不足两行，第二行的开头仍要写出。一般 detailed 写在源文件中，对象的定义之前。

• 如果一段代码既是声明也是定义，则 brief 和 detailed 写在一起。使用 \brief 命令，并且使用空行将两者分开。一般 brief 写在头文件中，对象的声明之前。

Doxygen常用指令

代码模板

File header

/// \file file_name.h
/// \brief Head file for class Ctest.
/// 
/// A detailed file description.
///
/// \author author_name
/// \version version_number
/// \date xxxx-xx-xx

Class

class 的定义和声明都在头文件中，所以使用下面这种 brief 和 detailed 结合的方式：

/// \brief A brief class description.
///
/// A detailed calss description, it
/// should be 2 lines at least.
class test {
    /// code
    /// code
    ///
};

Function

#!c++
/// \brief A brief function description.
/// \param p1 Description for p1.
/// \param p2 Description for p2.
/// \return Description for return value.
bool test(int n1, char c1);

/// \brief A brief function description.
/// 
/// A detailed description, it
/// should be 2 lines at least.
///
/// \param p1 Description for p1.
/// \param p2 Description for p2.
/// \return Description for return value.
/// \note something to note.
bool test(int n1, char c1);

Variable

变量一般使用 ///< 方式即可：

int m_a; ///< brief description for variable m_a
double m_b;  ///< brief description for variable m_b

Enum & Struct

类似于 Variable 的注释方式：

/// \brief A brief description.
/// 
/// A detailed description, it
/// should be 2 lines at least.
enum Tenum {
    em_1; ///< enum value em_1
    em_2; ///< enum value em_2
    em_3; ///< enum value em_3
}
emVar; ///< enum variable.

本栏目推荐文章
• API架构风格
• 浅谈6种流行的API架构风格
• 代码风格
• Matlab中常用快捷键：注释、自动对齐、跳转指定行、设置标签等
• 变量命名风格转换(Python)
• GNUMakefile及注释
• 【Python基础】Pycharm创建文件时，自动生成文件头注释
• 屎山代码风格指南（避免被优化&&避免被接盘）
• vue书写风格API
• vscode注释，单行注释，多行注释，文档头部注释，函数注释

注释 风格注释 风格 注释 风格doxygen visual 风格 风格 代码 风格cmd 风格rest 架构 风格api 风格restful 风格typora 字体 风格