Mitch Milam's Dynamics CRM and xRM Discussions

If you didn't know, placing your cursor on the line above a function and typing: /// will cause Visual Studio to insert a XML comment block, much like this:

This information is collected and written to an XML documentation file when you build your project ( assuming you've specified the XML file in the Project Properties ).

You can then use a tool like NDoc to generate Windows and HTML help file documentation for your project.  Here is an example of the XML comment shown above as a Windows Help file:

The problem I ran into this week was the inability to change the format of the XML comment block. It's just not something that Microsoft anticipated so they didn't create any method for customization.

Fortunately, they did include a macro called InsertDocComments in Visual Studio 2003 that will insert comments into all functions within a specified class file.  I simply modified this macro to produce the format I wanted:

Which, when read by NDoc, would generate the following documentation:

Installation:

1. Unzip InsertDocComments2.zip and you will find the InsertDocComments2.vb function.
2. Select Tools, Macros, Macros IDE.
3. In the Project Explorer window, right-click on the tree into which you would like to place this function.
4. Select Add Existing Item.
5. Select InsertDocComments2.vb and click OK.
6. Click the Save button.

The macro is now part of our macro library.

Additional Notes:

I also modified the macro to remove any exiting XML comments before inserting the new comments. I have yet to test this with VS2005, so I'm not sure if any changes will be required.

The one caveat I did notice about this macro is that the class file must be part of a project. If you just open a .CS file and attempt to run this macro, you'll receive an error.

Download it here.

If you find any errors, please let me know.