单行上的 Visual Studio XML 摘要注释

Posted 2023-02-21

【中文标题】单行上的 Visual Studio XML 摘要注释

【英文标题】：Visual Studio XML summary comment on single line

【发布时间】：2012-01-06 21:52:22

【问题描述】：

在Visual Studio中，如何将默认的XML摘要注释sn-p从三行改为一行？

目前它在我输入/// 时提供这个sn-p：

/// <summary>
/// 
/// </summary>

我想要这个更短的 sn-p：

///<summary></summary>

我的总结通常很简短，多余的 2 行是不必要的。

是否有此配置设置或一些可自定义的代码/自定义插件来解决此问题。

【问题讨论】：

我今天尝试这样做。我不喜欢提供的解决方案。 VS 带正则表达式： (///

【参考方案1】：

这是一个较老的问题，但我喜欢 Jason Williams 建议为此创建一个 sn-p，所以我这样做了。不是很复杂，但是复制粘贴更容易:)

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>Single line summary</Title>
      <Shortcut>summary</Shortcut>
    </Header>
    <Snippet>
      <Code Language="csharp">
        <![CDATA[/// <summary>$end$</summary>]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

您可以通过（可能很明显）更改<Shortcut> 值来更改快捷方式。

将其粘贴到名为 SingleLineSummary.snippet 的新文件中，并将其保存在文件夹 %USERPROFILE%\Documents\Visual Studio 2012\Code Snippets\Visual C#\My Code Snippets 中（修改以适合您的 Windows 和 Visual Studio 版本）。

如果您不熟悉 sn-ps，要使用它，只需将光标放在方法/属性/等上方，开始输入 summary，然后按几次 TAB。

【讨论】：

但是当您将鼠标指向某个呼叫时，MSVC 不会突出显示此类文档

很好的解决方案，虽然它的缺点是其他XML文档字段，如参数和返回值等，不会自动创建。

【参考方案2】：

我个人认为这应该是 VS 编辑器本身的一部分。我知道过去有人要求过。同时，sn-p 想法是一个不错的想法，但行为略有不同。如果您想保持相同的行为并且愿意购买第 3 方附加组件，那么 SubMain 有一个名为“GhostDoc Pro”的产品，只需稍加努力，它就会为您做到这一点。 （请注意，他们有一个免费的非“专业”版本“GhostDoc”，但我认为它不会起作用。）

如果你想走这条路，下面是它的工作原理。

安装 GhostDoc Pro 后，转到“工具”菜单。顶部将是一个新的弹出子菜单“GhostDoc Pro”。

转到工具 -> GhostDoc Pro -> 选项 -> 规则

您需要为每个要在其上生效的类型编辑 T4 模板。

点击规则，然后点击“编辑”

在顶部，修改

   /// <summary>
   ///<# GenerateSummaryText(); #>
   /// </summary>

公正

   /// <summary><# GenerateSummaryText(); #></summary>

在方法GenerateSummaryText中，将每个this.WriteLine修改为正好this.Write

点击确定保存，继续下一个模板。

在关闭选项页面之前，前往“常规”（来自“规则”）并选中“在记录此内容时突出显示自动生成的摘要”。这将导致新插入的自动文本被立即选择，因此如果您不喜欢它，您可以开始输入。当然，如果您更喜欢根本不生成文本，那么您也可以这样做，但您必须对 T4 模板进行更多修改。具体来说，您需要让GenerateSummaryText 只使用一行，

 this.Write(Context.ExecMacro("$(End)"));

这不会生成任何文本，但会将光标放在 2 个<summary> 标签之间。

---

旁注：

如果有人知道如何获得 ReSharper 或其他附加工具来执行此操作，我也会有兴趣看到该解决方案 - 如果只是出于好奇而没有其他原因。

【参考方案3】：

您可以根据自己的喜好手动设置注释格式，只要它仍然是有效的 xml。

最便宜的方法可能是禁用 Visual Studio 中的自动注释构建操作（工具 > 选项 > 文本编辑器 > C# > 为 /// 生成 XML 文档 cmets）并使用代码 sn-p 插入 /// <summary></summary> .

如果您希望默认格式为单行，和/或帮助保持格式整洁和可读，我的插件 Atomineer Pro Documentation 也可能会感兴趣。在众多选项中，有一个选项是使用紧凑的 1 行格式来表示任何足够短以适合单行的注释。它是专门为此设计的，因此它可能会更好地满足您的需求。

最后的建议是，还有其他几个插件（Resharper 等）可以生成简单的样板 xml doc-cmets - 我相信其中一些插件可以配置为使用特定的文本 sn-p。如果您已经有这样的插件，那么您的插件可能可以进行调整以提供您需要的单行格式，这种方式比上面建议的基本 Visual Studio 调整稍微高级一些。

【讨论】：

这是一个有趣的插件，但这并不能解决我的问题。

它确实有一个选项（在第二个选项选项卡上），用于将简单的 cmets 限制为“简单”（一行）格式。为了实现这一点，您可能需要禁用包含作者/日期信息（可以在选项的第一个选项卡中禁用）。然后，这将生成一个单行注释，直到它需要跨越多行。

另一种方法是尝试关闭 Tools>Options TextEditor\C#\Advanced "Generate XML documentation cmets for ///" 以禁用默认的 Visual Studio 处理（并关闭 AtomineerUtils // / 实时输入辅助选项），然后为 /// 添加一个代码 sn-p ，该代码将扩展为 /// <summary></summary>

【参考方案4】：

我今天试图这样做。我找不到将其更改为自动发生的方法，因此我想以后可以使用查找和替换以及正则表达式来做到这一点。这不是这个问题的好答案，但它似乎没有是一个好的答案，所有答案都是解决方法。这是一个很好的解决方法。

VS 与正则表达式

查找：(/// <summary>)\r\n\s*///\s*(.*)\r\n\s*///\s*(</summary>)

替换：$1$2$3

带正则表达式的记事本++

查找：(/// <summary>)\r\n\s*///\s*(.*)\r\n\s*///\s*(</summary>)

替换：\1\2\3