Ross Coded Classes

April 24, 2008

Using ReSharper to edit C# XML Documentation Comments

Filed under: .NET Tips — Tags: , — Ross Bradbury @ 8:23 am
I have recently been working on improving some of our code documentation.  I’ve found ReSharper to be very helpful in this area. (I’m using ReSharper 3.1.)
 
ReSharper’s Surround With Templates
 
I find a lot of places where paragraphs (<para>) need to be inserted, or where a member or class has been referenced by name only, and a reference using the <see> tag would be better.  One thing that I have found extremely helpful is to add my own “Surround With” templates in ReSharper.  Now I just have to highlight the text that I want to be in its own paragraph, and press Ctrl+Alt+J, D.  If I want to change a member name to a see tag I press Ctrl+Alt+J, E or use the ReSharper | Code | Surround with… menu and select the template I want.
 
Adding your own templates to ReSharper is easy:
  1. Navigate to ReSharper | Options | Templates | Surround With.
  2. Expand User Templates.
  3. Click the Create Template toolbar button.
  4. Fill in a name.
  5. Choose where it will be Available by clicking the hyperlink.  For these XML code documentation comments, I choose Language-specific for C# and check Everywhere (everywhere because none of the other options seemed to work for the comments.)
  6. Edit the template text to wrap $SELECTION$ with the text you want.
  7. Choose OK.
  8. If you like, you may now choose a position for your new template in the quick access list to choose which letter it can be accessed by.

Here are some of the Surround With templates I’ve set up for editing documentation comments:

Name Template Text
<para>
<para>$SELECTION$</para>
<see>
<see cref=”$SELECTION$”/>
<see> label
<see cref=”$SELECTION$”>$SELECTION$</see>
<note> <note type=”caution”>$SELECTION$</note>
 
I’ve found that using the template to insert the <see> tags sometimes cause ReSharper or Visual Studio to incorrectly complain that the code won’t compile by highlighting it; I can usually work normally, but if I get tired of the squiggly lines or if it gets too confused I just close the file and open it again.  I find this to be a minor inconvenience compared to the amount of time it saves.
 
ReSharper’s Live Templates
 
If you want to be able to insert text with ReSharper but you don’t want the text to surround the selection, you can use a Live Template.
 
Adding your own templates to ReSharper is pretty easy:
  1. Navigate to ReSharper | Options | Templates | Live Templates.
  2. Expand User Templates.
  3. Click the Create Template toolbar button.
  4. Fill in an abbreviation and description.  (I usually set the description to the same thing as the template text since these are usually small.)
  5. Choose where it will be Available by clicking the hyperlink.  For these XML code documentation comments, I choose Language-specific for C# and check Everywhere (everywhere because none of the other options seemed to work for the comments.)
  6. Edit the template text you want to insert.
  7. Choose OK.

Here are some of the Live templates I’ve set up for editing documentation comments:

Abbreviation Template Text
seet
<see langword=”true”/>
seef
<see langword=”false”/>
seen
<see langword=”null”/>

1 Comment »

  1. […] ReSharper 4.1 to edit C# XML Documentation Comments By Ross Bradbury This is a repost of this one updated to use ReSharper 4.1… I have recently been working on improving some of our code […]

    Pingback by Using ReSharper 4.1 to edit C# XML Documentation Comments « Ross Coded Classes — March 11, 2010 @ 10:33 am


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: