Visual Studio XML summary comment on single line

问题:

In Visual Studio, how do I change the default XML summary comment snippet from three lines to one line?

Currently it provides this snippet when I type ///:

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

I would like this shorter snippet:

///<summary></summary>

My summaries are often brief and the extra 2 line are unnecessary.

Is there a configuration setting for this or some customizable code/custom addon to fix this.

回答1:

This is an older question, but I liked Jason Williams's suggestion of creating a snippet for this, so I did. Not very complicated, but copy-and-paste is even easier :)

<?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>

You can change the shortcut by (probably obviously) changing the <Shortcut> value.

Paste that into a new file named SingleLineSummary.snippet and save it in the folder %USERPROFILE%\Documents\Visual Studio 2012\Code Snippets\Visual C#\My Code Snippets (modify to fit your version of Windows and Visual Studio).

If you're not familiar with snippets, to use this just put the cursor above a method/property/etc, start typing summary, and then hit TAB a couple of times.

回答2:

You can manually format the comment however you like it, as long as it remains valid xml.

The cheapest approach might be to disable the automatic comment-building action in Visual Studio (Tools > Options > Text Editor > C# > Generate XML Documentation comments for ///) and use a code snippet to insert /// <summary></summary>.

If you want the default format to be a single line, and/or help to keep the format tidy and readable, my addin Atomineer Pro Documentation may also be of interest. Among the many options is one to use a compact 1-line format for any comment that is short enough to fit on a single line. It is specifically designed to do this, so it may work better for your needs.

A final suggestion is that there are several other add-ins (Resharper, etc) that can generate simple boilerplate xml doc-comments - I believe some of these addins can be configured to use a particular text snippet. If you already have such an addin, it may be that yours can be adjusted to provide the one-line format you require, in a slightly more advanced manner than is possible with the basic Visual Studio tweak suggested above.

回答3:

Personally, I think this should be part of the VS editor itself. I've created a ticket at user voice that you may choose to vote on, if you like.

In the meantime, the snippet idea is a good one, but the behavior is slightly different. If you want to keep the same behavior and if you are willing to purchase a 3rd party add-on, then SubMain has a product called "GhostDoc Pro" that, with a little bit of effort, will do this for you. (Note that they have a free, non-"pro" version, "GhostDoc", but I don't think it will work.)

If you want to go this route, here's how it works.

1. After installing GhostDoc Pro, go to your Tools menu. At the top will be a new fly-out submenu, "GhostDoc Pro".
2. Go to Tools -> GhostDoc Pro -> Options -> Rules

3. You will need to edit the T4 template for EACH type that you want this to take effect on.

   1. Click on the rule and then hit "Edit"

   2. At the top, modify

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

      to be just

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

   3. In the method GenerateSummaryText, modify each this.WriteLine to be just this.Write
   4. Hit OK to save, move on to the next template.

4. 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)"));
   

   This will have it not generate any text, but will put the cursor between the 2 <summary> tags.

---

Side Note:

If anyone knows of a way to get ReSharper or other add-on tools to do this, I'd be interested in seeing that solution as well--if for no other reason than just curiosity.