.NET Code Comment Utilities

• Download executable - 121.4 KB
• Download source - 148.8 KB

Introduction

After writing a bunch of code for a C# framework I had just completed, I decided to dive into XML commenting my code.  I did some Google searches to find out how to make it go easier and faster.  I came across many utilities.  The 2 that stood out for me was SandBlaster and GhostDoc.  They gave me a good starting point. Sandblaster is great in that it generates help files based on the XML documentation Visual Studio generates.  GhostDoc is great in generating a base framework in documenting a method, property or other code chunk.

The problem was how to include examples of how to use the code in the documentation like you would see in MSDN web sites.  I could create the <example></example> XML Comments but there was no easy way to copy a code snippet from one part of my code and paste it into an <example> section of the XML documentation text.  I did some more Google searching but found nothing which would help with my problem.

Including example code in my documentation was critical to the scope of my project but trying to paste in code in the middle of <example> nodes and format was very slow and cumbersome.  So, I decided to write this program.

The goals of this program are simple.

1. Type in some comment using this program, then have this program generate the XML code, and then to be able to copy the XML comment from this program and paste it into the Visual Studio IDE.
2. Reverse the #1 process.  Copy an XML snippet from the Visual Studio IDE and paste it into this program's XML Code Comment textbox.  Then remove the line prefix characters (///) and generate the plain text to be ready for modification.
3. Type in some comment describing what the example code does into the Comment Text textbox in the XML Example Code Formatter window.  Then copy a code snippet from the Visual Studio IDE and paste it into the Code Text textbox.  Then have this program generate the <example> XML Code which can be copied and pasted into the Visual Studio IDE.
4. Reverse the #3 process.  Copy the <example> code comment from the Visual Studio IDE to the XML Comment textbox in the XML Example Code Formatter window.  Then click on the Generate Text button and remove all the line prefix characters (///) and have the code go back into the Code Text textbox and the Comment Text textbox for editing.

Background

It's a good idea to have a basic understanding of XML Documentation in order to use this program.  MSDN has some good information here.

Using the Software

Here's some tips when using this program.

Code Comment<-->Comment Text

• If "XML Comment" checkbox is checked, then Comment Text cannot have any special characters like "<>&".  These are reserved for inner XML tags.  This program supports having inner XML Documentation tags and allowing these special characters would confuse the parsing logic.  (Is the character a part of an XML tag or not?)  If you absolutely need those characters, you will need them to manually convert them to XML.  See www.w3schools.com/xml/xml_syntax.asp for more information.
• After you click on Generate Code Comment, the focus will move to Code Comment and select everything.  That way you can easily press Ctrl+C to copy the code comment and paste it into the IDE.
• After you click on Generate Comment Text the focus will move to Comment Text and select everything so you are ready to modify the text.
• Click on Save Data to save all the data on the form to the registry.

XML Example Code Formatter

• Comment Text cannot have any special characters like "<>&".  These are reserved for inner XML tags.  This program supports having inner XML Documentation tags and allowing these special characters would confuse the parsing logic.  (Is the character a part of an XML tag or not?)  If you absolutely need those characters, you will need them to convert them to XML.  See www.w3schools.com/xml/xml_syntax.asp for more information.
• The exception to the above rule is with Code Text.  Since it is assumed that there won't be any inner XML in the code block, when the XML Comment is generated, it puts the code text inside an XML Document and thereby converts all the special characters automatically.  This prevents the code causing help compile errors in Sandcastle.
• After you click on Generate XML Comment, the focus will move to XML Comment and select everything.  That way you can easily press Ctrl+C to copy the code comment and paste it into the IDE.
• After you click on Generate Text the focus will move to Comment Text and select everything so you are ready to modify the text.
• Click on Save Data to save all the data on the form to the registry.
• Reformat Code button - This is for dealing with some spacing issues with the Visual Studio IDE.  I noticed in Visual Studio, that the leading spaces were sometimes a mixture of spaces and tabs.  When I copied them from the IDE to Code Text, I got some really funky looking code.  So I added this button to replace all Tab (\t) characters in the Code Text textbox with 4 spaces.  That cleaned up most of the problems.

Points of Interest

I learned a lot about string manipulation and using LINQ to do some pretty nifty string searches.  Here's a list of some static methods I created in a static class called GBLMethods to make the process go smoothly.  See Documentation.chm (included in both downloadable files) for more details on these methods and to see Sandcastle's output after processing the XML documentation generated from this program.

History

03/19/2015 - Initial Release