Home > Coding Helpers > Coding Helpers – Add XML Comments

Coding Helpers – Add XML Comments

August 14th, 2012

Programming languages such as C# and Visual Basic support the creation of XML Documentation Comments, allowing developers to quickly annotate and document their source code to keep the documentation in a standard format and to gain benefit from the information as you code. Documentation is important to ensure that developers can quickly learn and use the source code.

Developers may use XML Comments to document code on user-defined types, including classes, structures, delegates, and enumerations. In addition, XML Comments may be attached to members, including fields, events, properties, indexers, and methods. In other words, these are specially formatted comments that decorate elements of your code. When you build your project with the corresponding option enabled, the XML Comments are extracted and combined in an XML file that resides in the same folder as the compiled application.

Documenting the source code should be an important part of the development process. If you get in the habit of documenting your source code as you write it, you will find that you can produce fully documented code much faster than if you write code and try and go back and create documentation later.

To help you document the source code, CodeRush provides the Add XML Comments code provider which may be very helpful for these purposes, if, for instance, you apply it to an existing method:

CodeRush Add XML Comments code sample

The code provider will generate the XML Documentation with summary, param, and return value tags as follows:

CodeRush Add XML Comments result

On the overridden members, the code provider will first look for the base member in the ancestor class. If the base member already provides XML documentation, the code provider will copy it to the member that overrides it:

CodeRush Add XML Comments result (overridden member)

Additionally, if a member implements the interface member from a referenced assembly, and the latter one provides the documentation in the corresponding XML file, the code provider will load it from the XML file for you, e.g.:

CodeRush Add XML Comments result (interface implemented member)

As a result, when you type this method call, you will see a nice hint with the corresponding documentation:

XML Documentation hint in Visual Studio

Don’t forget to enable the appropriate option to generate the XML documentation file when you build the project in the project properties window:

Project Properties - Generate XML Documentation File

Products: CodeRush Pro
Versions: 12.1 and up
VS IDEs: 2008 and up
Updated: Aug/14/2012
ID: C176

Similar Posts: