Working with XML comments in Visual Studio

Visual Studio XML Comments has been a part for quite a while. There are a number of xml tags that are supported which could help in documenting the API which you might have been building. In this post, I am going to discuss how the individual xml tags can help you and this can become a ready reference while developing an application in Visual Studio.

Lets say, we have created a class to generate Random number. The code looks like below :

Random random = new Random();
public int Generate(int seed)
{
return random.Next(seed);
}

When you want to call the method Generate, you will see something like this.

Now lets add some useful comments to the method.

Adding Summary of what method is doing, the Parameter list and a Return value. If you use /// just over the method in visual studio, the automatic conversion of the method occurs.

///
/// The method will generate random numbers based on a seed passed to it
///

///This is the value that indicates the seed /// A random number
public int Generate(int seed)
{
return random.Next(seed);
}

Here you can see we have defined the method completely using a Summary, Param for parameters and returns for return values. If I see the same method now, the documentation will come up as Visual Studio automatically picks up the xml and generates the documentation.

Here clearly the method is well descriptive to the developer who is going to use it.

You can also specify Exceptions that the method could generate.

///
/// The method will Generate random numbers based on a seed passed to it
///

///This is the value that indicates the seed /// Generate(20);
/// Can produce null reference when random is null
/// A random number
public int Generate(int seed)
{
return random.Next(seed);
}

Here in the code above, you can see we have added an example to specify the call to the method. we have also defined the Exception that the method can generate. If we see the same method again in visual studio, the method would look like :

This looks lot better now and also professional. Lets add something more to it. Lets add some more to it.

/// <summary>
/// The method will <c>Generate</c> random numbers based on a seed passed to it
/// <list type="bullet">
/// <item>
/// <description>Do not change the seed often</description>
/// </item>
/// <item>
/// <description>Random object once generated is reused per seed</description>
/// </item>
/// </list>
/// </summary>
/// <param name="seed">This is the value that indicates the seed</param>
/// <example>Generate(20);</example>
/// <remarks>Adding some remarks</remarks>
/// <see cref="http://msdn.microsoft.com/en-us/library/b2s063f7.aspx"/>
/// <seealso cref="https://dailydotnettips.com/"/>
/// <exception cref="NullReferenceException"/>
/// <returns>A random number</returns>
public int Generate(int seed)
{
return random.Next(seed);
}

The documentation would look pretty good and visual studio also allows to collapse the documentation and automatically embeds the xml inside the assembly as resource.

To have more references, you can try the link. 

BTW, it is worth mentioning, you can use some tools like GhostDoc which can generate the documentation for a method automatically.

Thanks, I hope this post will come handy.

Thanks