Using <code> and <example> Tags in C# XML Documentation Comments

Aug 16, 2018 • 4 Minute Read

Introduction

Code documentation describes the intent of a software's code. This includes the intent or description of a class and its members, the parameters and the expected result, or the return value. XML code comment must immediately precede a user-defined type (such as class, interface, or delegate) or its member (such as field, property, method, or event). XML code comments can be utilized by the IntelliSense feature of Visual Studio and VS Code to show information about a type or member; this information comes from what you put in your code documentation. The .NET compiler has an option that reads the XML documentation comments and generates XML documentation from them. This XML documentation can be extracted to a separate XML file.

The XML documentation comment starts with /// and can contain recommended tags that gives special meaning to the comment. Two of those recommended tags are <code> and <example> which we will be looking at in this guide.

Tag

This is used to specify a code snippet used to provide an example of how a type or members of a type can be used. In other words, it provides a code block for the documentation. This code block can be shown with special font and indentation in Visual Studio's IntelliSense. Below is an example utilizing this tag:

class Account
{
 public Account(int accountNo, int balance)
 {
   AccountNo = accountNo;
   Balance = balance;
 }
 public int AccountNo { get; set; }
 public int Balance { get; set; }

 ///<summary>Credit account with amount passed as parameter</summary>
 ///<code>
 ///var account = new Account(10, 2000);
 ///account.Credit(5000);
 ///</code>
 public void Credit(int amount)
 {
   Balance = amount + Balance;
 }
}

 The Credit() method has the XML comments. Between the opening and closing tags for <code>, we put the code we'd want to add to our method description.
  
    Tag 
  
 This tag allows example code within a comment to specify how a method or other library member may be used. This would also involve the use of the <code> tag. You can put a description between the opening and closing tags. Here's an example code following from our previous code:
 class Account
{
 public Account(int accountNo, int balance)
 {
   AccountNo = accountNo;
   Balance = balance;
 }
 public int AccountNo { get; set; }
 public int Balance { get; set; }

 ///<summary>Credit account with amount passed as parameter</summary>
 ///<example>After class initialisation, call this method:
 ///<code>
 ///var account = new Account(10, 2000);
 ///account.Credit(5000);
 ///</code>
 ///</example>
 public void Credit(int amount)
 {
   Balance = amount + Balance;
 }
}
 In VS Code it'll show you IntelliSense similar to this:
 
 
 Wrap Up
 XML code comments can be extremely useful in helping you, or other programmers who will use your code, to understand the code better. We looked at the <code> and <example> recommended tags which provides a way to document code examples. You saw how we can see this information through the IntelliSense. Use XML documentation comments as much as possible and give more meaning to your code. See the C# documentation for more recommended tags.