Coding Helpers – Add XML Comments
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:
The code provider will generate the XML Documentation with summary, param, and return value tags as follows:
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:
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.:
As a result, when you type this method call, you will see a nice hint with the corresponding documentation:
Don’t forget to enable the appropriate option to generate the XML documentation file when you build the project in the project properties window:
