用 Visual Studio 自动生成C/C++注释(Doxygen、XML)

文章目录

    • 引言
    • 方案一:用 Doxygen Comments 生成 Doxygen 风格注释
      • 1. 在VS中安装 Doxygen Comments 扩展
      • 2. 重启VS,启用扩展
      • 3. 使用 Doxygen Comments 自动生成注释
    • 方案二:用 GhostDoc 自动生成 xml 风格注释
      • 1. 安装 GhostDoc 扩展
      • 2. 重启VS,启用扩展
      • 3. 使用 GhostDoc 自动生成注释
    • 结语
    • 参考链接

引言

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

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

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

用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第1张图片

如果你比较喜欢 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,点击“下载”开始安装。
用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第2张图片
如果想查看详细说明,点击右侧的“详细信息”:
用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第3张图片

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 风格注释

用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第4张图片
GhostDoc 是一个 Visual Studio 扩展,适用于使用可自定义模板从源代码生成 XML 注释、维护干净的文档、生成多种格式的帮助文档。

GhostDoc支持

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

1. 安装 GhostDoc 扩展

工具——扩展——管理扩展,在联机中搜索:GhostDoc,点击“下载”开始安装。用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第5张图片

2. 重启VS,启用扩展

安装完控件后,需要先关闭 VS,才能继续安装扩展。安装完成后,重启VS,即可在【工具】看到GhostDoc。
用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第6张图片
对函数、类、结构体、接口等进行自动注释的快捷键是:Ctrl+Shift+D。

在【Options】——【Rules】中,可以对注释规则进行编辑修改。
用 Visual Studio 自动生成C/C++注释(Doxygen、XML)_第7张图片

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/

你可能感兴趣的:(C++编程笔记,visual,studio,c语言,c++,开发工具,文档)