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:
- Navigate to ReSharper | Options | Templates | Surround With.
- Expand User Templates.
- Click the Create Template toolbar button.
- Fill in a name.
- 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.)
- Edit the template text to wrap $SELECTION$ with the text you want.
- Choose OK.
- 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:
- Navigate to ReSharper | Options | Templates | Live Templates.
- Expand User Templates.
- Click the Create Template toolbar button.
- Fill in an abbreviation and description. (I usually set the description to the same thing as the template text since these are usually small.)
- 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.)
- Edit the template text you want to insert.
- 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”/>
|
I’m not sure where you are getting your info, but good topic.
I needs to spend some time learning much more or understanding more.
Thanks for fantastic information I was looking for this information for my mission.