HardCode: C# documentation using XML comments

During my initial days in the field of software development when the waterfall method was the in thing, we were told that documentation was a task that was to be performed somewhere at the end of the software development process. However as the number of modules get complex and with constantly changing requirements the agile development methodology has been adopted and also continuous documentation. This means that each developer can write documentation to their code such that if other developers have to access members the classes expose then they can be able to gain the advantages of IntelliSense.

We will need to take advantage of the C#'s XML documentation capabilities .

I will attempt to provide a basic approach subject to improvement that will be used.

If consistently used some of the benefits that we seek to accrue are:-

1. Being able to generate documentation using tools such as Ndoc.

2. Provide Intellisense just like any other .NET framework assemblies.

Ok enough with the banter.

Recommended tags

1. <summary></summary>

Provides a summary of the object

Should be used to describe a type or a type member.

The text for the <summary > tag is the only source of information about the type in IntelliSense and will also be displayed in the object Browser Window.

2. <param></param>

This is the name of a method parameter. Enclose the name in double quotation marks("").

To document multiple parameters, use multiple param tags.

The test here will be displayed in Intellisense, the Object Browser, and in the code comment web report.

3. <returns> </return>

This is a description of a methods return value

4. <exception></exception>

This tags will let you specify which exceptions can be thrown. It can be applied for methods, properties, event and indexers.

It takes an attribute cref whose value is a reference to an exception that is available form t he current compilation environment. Examples of values which go in there are:-

i. System.ArgumentException

ii. System.ArgumentNullException

iii. System.InvalidOperationException etc.

Basic approach

1. Write the code

2. When satisfied that everything is complete place the cursor directly above the class, interface, procedure etc. and press the backslash(\) thrice(\\\). This will create a template for the XML tags. If it’s a methods with parameters , a param tag for each one will be created.

3. when building remember to configure the project properties to export an XML file. This file should be named {projectname}.xml.

Sample code following the convention is given below.