用 Visual Studio 自动生成C/C++注释（Doxygen、XML）

引言

之前在网上搜索的时候，发现 VS 自动生成 C# 代码模板的帖子很多，C++的比较少。

所以整理一下，用 VS 开发 C++ 时可以用的自动注释工具。

方案一：用 Doxygen Comments 生成 Doxygen 风格注释

如果你比较喜欢 Doxygen 风格的注释，那你可以试试 Doxygen Comments 这个扩展，简洁好用。

• Doxygen Comments 可以为函数、标题和所有其他成员自动创建 doxygen 注释。

• Doxygen 是一种从带注释的源代码生成文档的工具。最初专为 C++ 创建，现在也支持 C、Objective-C、C#、PHP、Java、Python、IDL、Fortran、VHDL、Tcl 和 D。输出格式包括 HTML、Latex、RTF (MS-Word)、PostScript 、超链接的 PDF、压缩的 HTML 和 Unix 手册页。

1. 在VS中安装 Doxygen Comments 扩展

工具——扩展——管理扩展，在联机中搜索：Doxygen Comments，点击“下载”开始安装。

如果想查看详细说明，点击右侧的“详细信息”：

2. 重启VS，启用扩展

安装完控件后，需要先关闭 VS，才能继续安装扩展。安装完成后，重启VS，即可在已安装的扩展中找到 Doxygen Comments。

3. 使用 Doxygen Comments 自动生成注释

在h文件第一行输入/**，然后回车，就会生成以下文件头部注释：

/*****************************************************************//**
 * \file   sampleClass.h
 * \brief 
 *
 * \author Finn 
 * \date   April 2020
***********************************************************************/

在函数前面一行输入/**，然后回车，就会自动生成如下函数注释：

/**
 * .
 * 
 * \param country
 * \param city
 * \return 
 */
int add_city_to_country(string country, string city) {
	// TODO:...
}

方案二：用 GhostDoc 自动生成 xml 风格注释

GhostDoc 是一个 Visual Studio 扩展，适用于使用可自定义模板从源代码生成 XML 注释、维护干净的文档、生成多种格式的帮助文档。

GhostDoc支持：

• 自动生成 XML 注释
  立即生成格式正确的方法和类型文档。
  参数和返回值预先填充了智能描述。
• 可定制的 XML 注释模板
  使用模板精确地根据你的特定需求自定义生成的文档。
  标准 T4 模板允许你完全根据需要自定义文档生成。

1. 安装 GhostDoc 扩展

工具——扩展——管理扩展，在联机中搜索：GhostDoc，点击“下载”开始安装。

2. 重启VS，启用扩展

安装完控件后，需要先关闭 VS，才能继续安装扩展。安装完成后，重启VS，即可在【工具】看到GhostDoc。

对函数、类、结构体、接口等进行自动注释的快捷键是：Ctrl+Shift+D。

在【Options】——【Rules】中，可以对注释规则进行编辑修改。

3. 使用 GhostDoc 自动生成注释

在函数前面一行输入 /// ，然后就会自动生成如下函数注释：

/// 

/// Adds the city to country.
/// 
/// The country.
/// The city.
/// 
int add_city_to_country(string country, string city) {
	// TODO:...
}

这里函数的摘要、参数名解释都是纯自动生成的。

可以看出， GhostDoc 更智能，可以自己根据你的函数名，自动生成对应的介绍。

真是懒人福音，又可以少打几行字，尤其在参数多时非常省心。

结语

良好的起名习惯，可以让工具帮你自动生成清晰的注释，进而为自动生成文档做好准备。
现在的自动注释工具越来越方便，赶快尝试起来，减轻写注释的负担吧！

---

参考链接

https://www.doxygen.nl/download.html
https://computingonplains.wordpress.com/doxygen-and-visual-studio/
https://marketplace.visualstudio.com/items?itemName=sergeb.GhostDoc
https://marketplace.visualstudio.com/items?itemName=FinnGegenmantel.doxygenComments
https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/