Visual Studio单行XML摘要注释

Question

Visual Studio单行XML摘要注释

visual-studiocommentsxml-documentationcode-documentation

15

在Visual Studio中，我如何将默认的XML摘要注释片段从三行改为一行？

当前，当我输入 /// 时，它会提供以下代码片段：

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

我想要这个更简短的片段：

///<summary></summary>

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

是否有配置设置或可自定义的代码/自定义插件可以解决这个问题？

- Eugene

1

我今天试图做这个。我不喜欢提供的解决方案。使用 VS 和 Regex: (/// <summary>)\r\n\s*///\s*(.)\r\n\s///\s*(</summary>) 替换为: $1$2$3 使用 Notepad++ 和 Regex：查找: (/// <summary>)\r\n\s*///\s*(.)\r\n\s///\s*(</summary>) 替换为：\1\2\3 - Rhyous

4个回答

3

个人认为这应该是VS编辑器本身的一部分。我知道这在过去已经被要求过。与此同时，片段的想法是好的，但行为略有不同。如果您想保持相同的行为，并且愿意购买第三方插件，则SubMain有一个名为“GhostDoc Pro”的产品，通过一点努力，它将为您完成此操作。（请注意，他们有一个免费的非“pro”版本，“GhostDoc”，但我不认为它会起作用。）

如果您想选择这条路，请看以下步骤。

After installing GhostDoc Pro, go to your Tools menu. At the top will be a new fly-out submenu, "GhostDoc Pro".
Go to Tools -> GhostDoc Pro -> Options -> Rules
You will need to edit the T4 template for EACH type that you want this to take effect on.
Click on the rule and then hit "Edit"

At the top, modify

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

to be just

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

In the method GenerateSummaryText, modify each this.WriteLine to be just this.Write
Hit OK to save, move on to the next template.
Before closing the options page, head up to "General" (from "Rules") and check the "Highlight auto-generated summary when Document This". This will cause the newly inserted auto-text to be selected off the bat so if you don't like it, you can just start typing. Of course, if you prefer to have the text just not generated at all, then you can do that, too, but you will have to modify the T4 templates a bit more. Specifically, you'll need to have GenerateSummaryText just use a single line,
```
 this.Write(Context.ExecMacro("$(End)"));
```

这将使其不生成任何文本，但将光标放在两个 <summary> 标记之间。

顺便说一下：

如果有人知道如何让 ReSharper 或其他附加工具来完成这个操作，我也很感兴趣看看这个解决方案——即使只是出于好奇心。

- David

2

今天我试图实现这个功能。我找不到自动更改的方法，所以我想用查找和替换以及正则表达式来实现。虽然这不是这个问题的好答案，但似乎没有好答案，所有的答案都是变通方法。这是一个好的解决方案。

使用正则表达式在VS中进行替换

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

替换: $1$2$3

使用正则表达式在Notepad++中进行替换

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

替换: \1\2\3

- Rhyous

这是将所有现有摘要压缩成单行内容的最佳方式。 - undefined

2

您可以手动格式化评论，只要它保持有效的xml格式。最便宜的方法可能是在Visual Studio中禁用自动生成注释的功能（工具>选项>文本编辑器>C#>为///生成XML文档注释），并使用代码片段插入///<summary></summary>。如果您希望默认格式为单行，并且/或者帮助保持格式整洁可读，则我的插件Atomineer Pro Documentation也可能会引起您的兴趣。其中许多选项中的一个是使用紧凑的1行格式来处理任何短到足以适合在单行上的注释。它专门设计用于此，因此它可能更适合您的需要。最后一个建议是有几个其他的添加程序（Resharper等）可以生成简单的样板xml doc-comments - 我相信这些添加程序中的一些可以配置使用特定的文本片段。如果您已经拥有这样的插件，那么您可能可以调整它，以更高级的方式提供您所需的一行格式，比上述基本Visual Studio调整的方式稍微先进一些。

- Jason Williams

那是一个有趣的附加组件，但它并没有解决我的问题。 - Eugene

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

1

另一种方法是尝试关闭“工具”>“选项”>“文本编辑器\ C#\高级”中的“为///生成XML文档注释”来禁用默认的Visual Studio处理方式（也要关闭AtomineerUtils ///实时输入辅助选项），然后添加一个代码片段///，它只扩展到/// <summary></summary>。 - Jason Williams

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Nick · Accepted Answer

这是一个较旧的问题，但我喜欢Jason Williams的建议，他建议为此创建一个代码段，所以我这样做了。虽然不是很复杂，但复制和粘贴更容易 :)

<?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版本进行修改）。

如果您不熟悉代码片段，只需将光标放在方法/属性等上方，开始输入summary，然后按TAB键几次即可使用它。