Visual Studio XML summary comment on single line

Question

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.

Swelling

I as trying to do this today. I didn't like the solutions provided. VS with Regex: (/// <summary>)\r\n\s*///\s*(.*)\r\n\s*///\s*(</summary>) Replace: $1$2$3 Notepad++ with regex. Find: (/// <summary>)\r\n\s*///\s*(.*)\r\n\s*///\s*(</summary>) Replace: \1\2\3 – Large

Answer 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.

Electioneer

but such documentation does not highlighted by MSVC when you point a mouse on some call – Belamy

Good solution, though it has the drawback that other XML documentation fields, like parameters and return value and so forth, will not be automatically created. – Forestation

Answer 2

Personally, I think this should be part of the VS editor itself. I know it's been requested in the past. 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.

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

5. At the top, modify

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

   to be just

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

6. In the method GenerateSummaryText, modify each this.WriteLine to be just this.Write

7. Hit OK to save, move on to the next template.

8. 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.

Sensitivity

Answer 3

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.

Submarginal

That's an interesting addon, but that doesn't solve my problem. – Swelling

It does have an option (on the second options tab) for simple comments to be restricted to a "simple" (one line) format. In order to achieve this you may need to disable the inclusion of the author/date information (which can be disabled in the first tab on the options). This will then generate a single-line comment until such a time as it needs to span more than one line. – Submarginal

Another approach would be to try turning off Tools>Options TextEditor\C#\Advanced "Generate XML documentation comments for ///" to disable the default Visual Studio handling (and also turn off the AtomineerUtils /// live typing aids option as well), and then add a code snippet for /// that just expands to /// <summary></summary> – Submarginal

Answer 4

I was trying to do this today. I couldn't find a way to change it to happen automatically, so I figured I could do it afterward with find and replace and regex. It isn't a good answer to this question, but it doesn't appear there is a good answer and all the answers are workarounds. This is a good work around.

VS with Regex

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

Replace: $1$2$3

Notepad++ with regex

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

Replace: \1\2\3

Large

This is the best way to compact all exists summary which is single line content. – Ergot