文档章节

C++标准注释原则 - 基于doxygen的C++注释

尘中远
 尘中远
发布于 2016/05/12 23:50
字数 2366
阅读 2
收藏 0
点赞 2
评论 0


标注总述

下载国外的源代码,往往能看到附带的说明文档,文档都有详细的说明,大部分文档都可以通过doxygen这个跨平台软件生成,doxygen并不能随便读取你的C++的注释,必须按照一定的规则才能生成,所以在编写代码时,一定要按照标准写注释,否则会为以后带来许多麻烦

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

先看看总述:


文件头:

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

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


类说明:
/// \brief Ctext的doxygen测试
///
/// 作doxygen测试用
class Ctext
{
}


函数标注
   方法1:
/// \brief 函数简要说明-测试函数
    /// \param n1 参数1
    /// \param c2 参数2
    /// \return 返回说明
    bool text(int n1,Ctext c2);
   方法2:
/// \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的说明
    };


1.文件头说明

文件头说明按照如下格式写
/*!
* \file Ctext.h
* \brief 概述 
* 
*详细概述 
* 
* \author 作者,包含email等 
* \version 版本号(maj.min,主版本.分版本格式) 
* \date 日期 
*/

上注释等下于下面这种写法
/*!
 \file Ctext.h
\brief 概述 
详细概述 
\author 作者,包含email等 
\version 版本号(maj.min,主版本.分版本格式) 
\date 日期 
*/


对于vs编译器可能中间那行*号比较麻烦,可以不写,对于Qt这种要去掉中间的*号反而是件麻烦事就不用去掉
用doxygen生成注释如下效果




2. 命名空间

命名空间说明如下写

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

}

doxygen的说明写法都是类似于
/// \brief
/// 
///

以下将会见到很多这样的写法
上注释的doxygen效果如下


3. 类说明


类的注释和函数一样,

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

上注释用doxygen生成文档效果如下:




4.函数注释原则

函数详细注释位于头文件,cpp文件只对函数做简明注释
cpp文件不做///的注释,否则会和头文件重叠

4.1 函数简要说明

注释方法1:
/// \brief 函数简要说明-测试函数
    /// \param n1 参数1
    /// \param c2 参数2
    /// \return 返回说明
    bool text(int n1,Ctext c2);

简要注释此注释会让doxygen生成函数简要说明和参数说明
生成结果如:


4.2 函数简要说明+详细说明


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

上注释用doxygen生成文档效果如下:



4.3 不带简要说明的函数标注

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

上注释用doxygen生成文档效果如下:

这里没有说明



4.4 带参见的写法

/// \brief 函数说明-测试函数4
    /// \param n1 参数1说明
    /// \param c2 参数2说明
    /// \return 返回说明
    /// \see text3 text2 text
    bool text4(int n1,Ctext c2);

上注释用doxygen生成文档效果如下:



\see 上可以带中文等说明,doxygen会自动识别代码里存在的函数

5.变量注释


变量注释用///< 对变量进行说明,对于详细信息可以加\brief
  
int m_a;     ///< 成员变量1m_a说明
    double m_b; ///< 成员变量2m_b说明

    /// \brief 成员变量m_c简要说明
    ///
    /// 成员变量m_c的详细说明,这里可以对变量进行
    ///详细的说明和描述,具体方法和函数的标注是一样的
    float m_c;

如果变量需要详细说明的可已按照m_c的写法写,注意,m_b和m_c之间一定需要空行,否则会导致m_b的简述消失
上注释用doxygen生成文档的具体效果如下





6.枚举


枚举变量的标注方法如下

/// \brief xxx枚举变量的简要说明
    ///
    /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明
    ///的写法是一致的。每个枚举变量下可以进行单独说明
    enum{
        em_1,///< 枚举值1的说明
        em_2,///< 枚举值2的说明
        em_3 ///< 枚举值3的说明
    };


枚举的总体说明和函数的写法一致,每个枚举变量的说明和变量的说明写法一致
上注释用doxygen生成效果如下:







7.doxygen的设置和中文问题


7.1 生成私有成员


如果想生成私有成员(doxygen默认不生成私有成员),可以如下设置
选择Expert标签的Build项,勾选EXTRACT_PRIVATE即可

7.2 中文问题

中文有时候是乱码
对于vs2010的文档,默认是gb2312,可以设置
Expert标签的Project项目的DOXYFILE_ENCODING 为 GB18030
INPUT_ENCODING 为 GB18030

另外Project项目的生成语言(OUTPUT_LANGUAGE)选择Chinese


对于其他的代码文件如果中文乱码,可以用文本编辑器转换代码文本编码为UTF-8带BOM的(注意这有可能影响代码,所以转换编码时要备份),再进行导出。





8.vs2008、vs2010 及以上IDE的快速标注方法

vs2010 等编译器并不能像Qt Creator那样生成上述标注样式,但是可以集成到vs的工具栏里,集成方法如下图所示:


这样在标注时可以直接从工具箱拖曳了,非常方便



附:

Ctext.h

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

#pragma once
/// \brief 命名空间的简单概述 
/// 
///命名空间的详细概述
namespace text
{

}

/// \brief Ctext的doxygen测试
///
/// 作doxygen测试用
class Ctext
{
public:
    Ctext(void);
    ~Ctext(void);
    /// \brief 函数简要说明-测试函数
    /// \param n1 参数1说明
    /// \param c2 参数2说明
    ///    \return 返回说明
    bool text(int n1,Ctext c2);
    /// \brief 函数简要说明-测试函数
    /// 
    /// 函数详细说明,这里写函数的详细说明信息,说明可以换行
    /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行
    /// ,详细说明之前不需要任何标识符
    /// \param n1 参数1说明
    /// \param c2 参数2说明
    ///    \return 返回说明
    bool text2(int n1,Ctext c2);
    /// 函数说明-测试函数
    /// 
    /// 函数详细说明,这里写函数的详细说明信息,说明可以换行
    /// ,如这里所示,同时需要注意的是详细说明和简要说明之间必须空一行
    /// ,详细说明之前不需要任何标识符
    /// \param n1 参数1说明
    /// \param c2 参数2说明
    ///    \return 返回说明
    bool text3(int n1,Ctext c2);
    /// \brief 函数说明-测试函数4
    /// \param n1 参数1说明
    /// \param c2 参数2说明
    ///    \return 返回说明
    /// \see text3 text2 text
    bool text4(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的说明
    };
};

另外可看看这篇文章里面的注释:http://blog.csdn.net/czyt1988/article/details/21743595



 

© 著作权归作者所有

共有 人打赏支持
尘中远
粉丝 1
博文 26
码字总数 47436
作品 0
朝阳
程序员
C/C++之C及C++发展史及标准

Tips:  1. 本人当初学习C/C++的记录。  2. 资源很多都是来自网上的,如有版权请及时告知!  3. 可能会有些错误。如果看到,希望能指出,以此共勉! C和C++   C++是C语言的一个超集。C...

zcshoucsdn
2017/03/06
0
0
EclipseforC/CPP 之配合 doxygen + graphviz 生成HTML代码文档

JAVA语言中的代码注释那是相当好的一个东西,尤其是使用了Eclipse之后,简直是程序员的福音。小弟前几天用了一下午的时间,经过在网上的查找以及我一点点的探索,终于搞定在windows平台下,使...

小代码2016
2014/10/20
0
0
强大不代表完美——C++几个不方便的地方。

引言:本文自工作以来使用过C++、Java、Python、Groovy、Objective C、Lisp,我最初学的就C++的,当时对她情有独钟,灵活和强大充分体现了她的智慧,随着你对她理解的深入,你会发现随便一段...

爱捣鼓
2014/02/20
0
0
doxygen学习笔记 2012-02-28

Doxygen把自己定义为“Source code documentation generator tool”(源代码文档生成工具)。Doxygen提供一种维护文档的机制。Doxygen可以做下面的事情: 1、从已经文档化的代码中抽取并生成...

qbcs
2012/06/08
0
1
Cocos2dx程序菜单项的添加

在原有的项目》属性》配置属性》常规》项目默认值》MFC的使用》设置》在共享DLL当中使用MFC 在CCEGLView_win32.h头文件当中27行添加,28行注释 #include <afxwin.h>//#include <Windows.h> ...

Amamatthew
2014/06/23
0
0
Java程序员如何高效而优雅地入门C++

Java程序员如何高效而优雅地入门Cpp,由于工作需要,需要用C++写一些模块。关于C++ 的知识结构,虽说我有过快速学习很多新语言的经验,但对于C++ 我也算是老手,但也还需要心生敬畏,本文会从...

小欣妹妹
04/23
0
0
auto-complete-clang-async 设置 ac-clang-cflags

auto-complete-clang-async 貌似不错,这里是项目主页 https://github.com/Golevka/emacs-clang-complete-async 文档上介绍说可以通过下面的方法设置clang参数: 调用ac-clang-set-cflags命令...

ChanningBJ
2013/08/22
0
1
C语言编程入门学习:C语言实现猜数字小游戏

C语言是面向过程的,而C++是面向对象的 C和C++的区别: C是一个结构化语言,它的重点在于算法和数据结构。C程序的设计首要考虑的是如何通过一个过程,对输入(或环境条件)进行运算处理得到...

小辰带你看世界
05/30
0
0
C++ STL编程轻松入门 3

2 牛刀小试:且看一个简单例程   2.1 引子   如果你是一个纯粹的实用主义者,也许一开始就可以从这里开始看起,因为此处提供了一个示例程序,它可以带给你有关使用STL的最直接的感受。是...

暖冰
2015/11/21
0
0
C语言/C++编程新手学习常见问题

C语言是面向过程的,而C++是面向对象的 C和C++的区别: C是一个结构化语言,它的重点在于算法和数据结构。C程序的设计首要考虑的是如何通过一个过程,对输入(或环境条件)进行运算处理得到...

小辰带你看世界
05/11
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

c++ qt 组播总结

每个人都有不同的认知规律和习惯, 有的人喜欢搞一套严密的大理论, 论述起来滔滔不绝, 不管自己懂不懂, 反正读者/听者是没搞懂。 有的人喜欢从实践出发, 没看到代码, 不运行一下, 不看...

backtrackx
8分钟前
0
0
Sublime text2安装json格式化插件SublimePrettyJson[Windows]

一、下载SublimePrettyJson插件包 https://github.com/dzhibas/SublimePrettyJson 二、将下载的文件解压放到在package目录下面 C:\Users\lucky\AppData\Roaming\Sublime Text 3\Packages 每个......

lazy~
8分钟前
0
0
安装vue-cli 报4058错误

1. 4058是网络代理错误。 安装淘宝源修改一下就可以了: npm --registry https://registry.npm.taobao.org info underscore 改为cnpm执行: cnpm install --global vue-cli 安装成功: 试试版...

MrBoyce
10分钟前
0
0
CPU飙升分析

1、top -----看具体的进程 2、top -H -p pid ------该进程的线程 3、printf 0x%x 15248 ------将线程改为16进制 4、jstack 进程...

北极之北
12分钟前
1
0
新生代Eden与两个Survivor区的解释

聊聊JVM的年轻代 1.为什么会有年轻代 我们先来屡屡,为什么需要把堆分代?不分代不能完成他所做的事情么?其实不分代完全可以,分代的唯一理由就是优化GC性能。你先想想,如果没有分代,那我...

浮躁的码农
14分钟前
0
0
【JVM】JSTATD结合Java VisualVM进行远程监控JVM运行情况(二)

内存泄露指的是程序中动态分配内存给一些临时对象,但是对象不会被GC(java垃圾回收机制gabage collection)所回收,它始终占用内存。即被分配的对象很大但已无用; 内存溢出指的是程序运行过...

大白来袭
17分钟前
2
0
聊聊ribbon的超时时间设置

序 本文主要研究一下ribbon的超时时间设置 配置 实例 ribbon: ReadTimeout: 10000 ConnectTimeout: 10000 MaxAutoRetries: 0 MaxAutoRetriesNextServer: 1 eureka: enabled: ......

go4it
26分钟前
0
0
一行代码结果叹为观止,能做到这么极致的也只有python了

Python 这门语言非常的有趣,不仅可以做高大上的人工智能、大数据、机器学习。还可以用来做 Web、爬虫。还有其它很多的应用。今天我就给大家展示下一行 Python 代码都可以做些什么。 一行打印...

猫咪编程
29分钟前
2
0
KingShard使用

对于kingshard的功能,在git中可以看到明确的功能说明 主要功能: 1. 基础功能 支持SQL读写分离。 支持透明的MySQL连接池,不必每次新建连接。 支持平滑上线DB或下线DB,前端应用无感知。 支...

mickelfeng
31分钟前
0
0
Linux 下 查找某个字符串

如果你想在当前项目下 查找 "test" 这个字符串,可以这样: grep -rn "test" * * : 表示当前目录所有文件,也可以是某个文件名-r 是递归查找-n 是显示行号-R ...

nsns
31分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部