在 Visual Studio 2010 C++ 中为 /// 生成 XML 文档注释

Posted 2023-02-21

【中文标题】在 Visual Studio 2010 C++ 中为 /// 生成 XML 文档注释

【英文标题】：Generate XML documentation comments for /// in Visual Studio 2010 C++

【发布时间】：2011-05-02 20:47:30

【问题描述】：

我需要用摘要、返回、参数标签来注释我的函数原型（用 C/C++ 编写）。如何说服 Visual Studio 在 C# 中的三个正斜杠后插入 xml 标签？我找到了一种解决方案。当我在 C++ 项目中重命名 xx.h xx.cs 时，我可以使用 /// 来生成 xml cmets（xml cmets 中的 IntelliSense 也可以）。一定有更好的方法，不是吗？ 手动编写它会杀了我。我会感谢每一个有用的评论。

/// <summary>
/// 
/// </summary>
/// <param name="aa"></param>
/// <returns></returns>
bool function1(TypeX aa);

【问题讨论】：

这是 C++ 和 C# 语言团队使用不同 Intellisense 引擎的结果。据我所知，在 C++ 文件中键入 /// 时，您将无法获得 C# 自动补全。

没有。当一个文件有cs扩展名时，我可以。重命名文件来写 xml 注释是不合适的，但它会有所帮助。

虽然我同意应该有一种方法可以让 IDE 为你做这件事，关于 It would kill me to write it manually. 真的吗？如果您在这些文档块中的文本中足够冗长（这样您就可以在忘记是您编写代码之后理解如何使用代码）那么/// 和 xml 的开销标签实际上并没有那么多。 :-) -- 或者，严重错误地引用了电影第十三勇士“学习打字更快”。 :-) :-)

@JesseChisholm 这确实是个问题。因为这个，我真的想在某个时候停止使用 C++。

【参考方案1】：

此功能最终将作为本机功能加入 Visual Studio 2019 16.6 （连同自动生成的标头和 C++20 完全支持）：

https://docs.microsoft.com/en-us/visualstudio/releases/2019/release-notes-preview

这么多年过去了……

【参考方案2】：

对于 C++/CLI

这些说明适用于Visual Studio 2015 Update 2。

首先，打开 XML 文档。这会生成一个元数据文件，这意味着 cmets 将在外部可见，包括 C#。

接下来，根据@tcb的回答，安装CppTripleSlash。重新启动 Visual Studio，一切顺利。

【参考方案3】：

这适用于 C++/CLI

另一种方法是使用ILSpy 将C++/CLI 代码转换为C#。然后，在 C# 中，您可以编写带有 IntelliSence 支持的 cmets。然后只需将 cmets 复制到 C++/CLI 项目中，编译即可：-)

配置 Visual Studio (2013) 以使用 ILSpy

​​>

下载 ILSpy 二进制文件 通过打开“工具/外部工具/添加”在 Visual Studio 中添加新工具条目。 这里输入路径ILSpy.exe 用于命令，$(TargetPath) 用于参数，$(TargetDir) 用于初始目录。 应用并关闭窗口。 （工具选项卡中显示一个新条目） 创建一个新的空 C# 项目。

使用它

如果您随后打开 C++/CLI 项目的任何文件并激活“工具”选项卡中的新条目，则会出现一个窗口 (ILSpy)，显示您的程序集已转换为 C# 代码。将该代码复制到位于 C# 项目中的文件并编写 XML cmets。

【参考方案4】：

在 Visual Studio 2010 C++ 中，您可以定义宏来为您插入内容。

定义一个宏来插入基本函数标题摘要行。

/// <summary> </summary>

另一个用于空参数行，另一个用于返回行。

/// <param name=""> </param>

和

/// <returns> </returns>

只需三个宏即可满足您的大部分需求。如果你用得够多，那么为/// <remarks></remarks> 和/// <exception name=""></exception> 和<see cref=""/> 添加一个宏，任何你没有足够使用的宏都需要手动输入。

是的，您必须手动输入参数的名称。 :) 宏不能做所有事情。 :)

见：MSDN : VS2010 : How to Record Macros

见：MSDN : VS2010 : How to Run macros

更新：当我写这个答案时，我不知道这些线程：

SO: Macros don't run in VS2010

MS: Macros broken in VS2010 by security fix Feb 2014（带有建议的解决方法）

【参考方案5】：

CppTripleSlash 在输入 /// 时在 c++ 文件中创建 xml doc 注释存根，类似于 Visual Studio 中可用于 c# 的内容。这也有一些用于完成 XML doc cmets 的基本智能感知。

【讨论】：

这在 Visual Studio 2015 Update 2 的 C++/CLI 中出色地工作。需要在功能启动之前重新启动 VS。

我不能推荐它。它要求开发人员更改他们的代码以便在所有情况下都可以工作，这对于只添加 cmets 的工具来说是不行的。此外，它的行为不像我们在 C# 中所习惯的那样，有时会产生更多的工作。例如，它不会在新行中插入///，并且每次输入三个斜杠时都会愚蠢地插入<summary> 标签。

【参考方案6】：

GhostDoc 现在将为 C++ 元素插入 XML cmets。只需将光标放在一个元素上，然后按 Ctrl+Shift+D。

GhostDoc 有一个供个人使用的免费版本，已经可以做到这一点。

【参考方案7】：

看看这个插件： GhostDoc

【参考方案8】：

此功能未内置。您可以尝试使用Visual Studio add-ins。我自己没有使用过Atomineer Utils Pro Documentation，但它看起来很有希望。它生成文档 cmets 并支持 C++。不过它要花 10 美元。

【讨论】：

Atomineer Utils 是您想要的产品。在测试了 10 分钟的免费试用版后，我欣然支付了 10 美元。如果您使用过 C# 或 VB，它的功能就像您所期望的一样。