vs注释

使用VA助手如何快速添加注释(按doxygen注释规范)

3D视觉工坊

​

博众精工科技股份有限公司 视觉算法工程师

本文首发于微信公众号「3D视觉工坊」：使用VA助手如何快速添加注释(按doxygen注释规范)

此处分享一下我在工程中使用VA助手进行快速注释的小技巧，感兴趣的小伙伴可以借鉴下。

第一步：打开VS中的VA助手小工具，见图1。

第二步：选择「Edit VA Snippets」，见图2。

第三步：添加对命名空间(namespace)的注释模板，见图3。
其中，对命名空间的注释模板内容demo粘贴如下：
/// @namespace ???
/// @brief ???

第三步：添加对类(Class)的注释模板，见图4.
其中，对类的注释模板内容demo粘贴如下：

/// @class <class‐name>
/// @brief This is a brief description.
/// @note mattersneeding attention

第四步：添加对成员函数(method)的注释模板，见图5。

其中，对成员函数的注释模板内容demo粘贴如下：

/// @brief Thisis a brief description.
/// @param[in] inArgName input argument description.type name:purpose(Range)
/// @param[out] outArgName output argument description.
/// @Return: $SymbolType$:description of the return value

第五步：对头文件(header)的注释模板，见图6.

/// @file .$FILE_BASE$.$FILE_EXT$

/// @brief ???（函数功能）
/// @author **********
/// @date $YEAR$-$MONTH_02$-$DAY_02$

/// @since 1.0.0.0

/// @ingroup pcp-filter

/// @Copyright (c) 2019, BOZHON Precision Industry Technology Co.,Ltd, www.boozhong.com. All rights reserved.

第六步：对结构体(struct)的注释模板，见图7.

/// @struct DB_INFO???
/// @brief 数据库信息结构体???

第七步：对枚举类型(enum)的注释模板，见图8.

/// @enum DB_TYPE???
/// @brief 数据库类型???

第八步：对宏类型(macro)的注释模板，见图9.

/// @brief 导出符号定义

用法：简单举个例子，比如我们对于filter_t.h的头文件想给出注释，我们只要在VS中，
输入「//Header」，即可得到如下的注释行。
/// @file filter_t.h
/// @brief ???（函数功能）
///
/// @author *******
/// @date 2019-04-18
/// @since 1.0.0.0
/// @ingroup pcp_filter
/// @Copyright (c) 2019, **** Precision Industry Technology Co.,Ltd, www.****.com. All rights reserved.

修改下上面的函数功能，写上你对这个函数功能的具体注释即可。

那么，我们为什么要进行按照doxygen注释规范来进行注释呢，这样做有什么好处呢？

我们可以使用上述的注释，快速生成如下图所示的库说明文档。

至于doxygen的具体使用方法，已经在【3D视觉工坊】知识星球中给出了介绍，如果愿意学习了解的同学，可以前往查看。

上述内容，如有侵犯版权，请联系作者，会自行删文。

荐读

一分钟详解PCL-1.8.1从源码搭建开发环境一(Boost库的编译)

关注微信公众号「3D视觉工坊」，后台回复关键词——知识星球，前往【3D视觉工坊】知识星球。

最近被安利了一款工具，名字叫Doxygen，使用它能把项目的代码和文档导出为HTML、RTF、LATEX等形式，而且还能把代码的组织结构绘制成图，有效减轻阅读大型项目的源码时的困难。

安装Doxygen

Doxygen: Main Page

安装GraphViz

Graphviz - Graph Visualization Software

下面用doxygen的GUI工具DoxyWizard来运行Doxygen，实现对Django的源码进行提取。

配置项目

1. 选择项目名称，源码目录和文档输出目录。

配置Output

配置diagrams选项

1. 配置Input选项

配置Dot

1. 启动doxygen，查看结果。

使用文档

查看命名空间

查看类的继承关系

当然，这只是其中一部分...

查看django.http.response的参考

进入HttpResponse这个类的说明（Doxygen支持Markdown格式的注释）

查看定义

查看函数调用图

查看索引

文件列表

Doxygen支持多种语言（C，C++，JAVA，PHP，Python...），还有许多强大的功能（BUILD，PATTERNS...），麻麻再也不用担心我写文档了！