XML Documentation Comments In C#
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. There are various syntaxes for comments in C#. One of these is XML Documentation comments, sometimes called XML comments, which starts with a triple slash - ///. XML 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 generate XML documentation from them. This XML documentation can be extracted to a separate XML file. XML documentation comments must immediately precede a user-defined type (such as class, interface, or delegate) or its member (such as field, property, method, or event).
XML Documentation Comments
Let's look at a simple class such as the following:
1class Program
2{
3 static void Main(string[] args)
4 {
5 Console.WriteLine("Hello World!");
6
7 Console.ReadKey();
8 }
9
10 ///The left side operand for an arithmetic operation
11 static int Operand1 { get; set; }
12
13 ///The right side operand for an arithmetic operation
14 static int Operand2 { get; set; }
15
16 /// This method adds two integers
17 static int Add(int operand1, int operand2)
18 {
19 return operand1 + operand2;
20 }
21
22 ///This method subtracts two integers
23 static int Subtract(int operand1, int operand2)
24 {
25 return operand1 - operand2;
26 }
27}We added XML comments to properties Operand1 and Operand2, and to methods Add and Subtract. When you call any of these properties or methods with XML comments, they appear with a text description.
There are recommended XML tags you can use with XML comments. There are the <remarks>, <summary>, and <returns> tags.
The Remarks Tag
The <remarks> tag specifies a general commentary or description for a type, such as a class or structure.
1///<remarks>Holds user basic data like their names and address
2class User
3{
4 string FirstName { get; set; }
5
6 string LastName { get; set; }
7}The Summary Tag
The <summary> tag is used to add general commentary explaining a method or other class members. If <remarks> is for a general commentary for a class, <summary> does the same but for the members of the class.
1///<summary>Subtract two integers and return the result</summary>
2static int Subtract(int operand1, int operand2)
3{
4 return operand1 + operand2;
5}The Returns Tag
The <returns> tag documents the return value of a method. So we can update the previous code to add <returns> tag as follows:
1///<summary>Subtract two integers and returns the result</summary>
2///<returns>the difference between the two operands</returns>
3static int Subtract(int operand1, int operand2)
4{
5 return operand1 + operand2;
6}End Result
Applying the tags will look like the following:
1///<remarks>Starts the console application</remarks>
2class Program
3{
4 static void Main(string[] args)
5 {
6 Console.WriteLine("Hello World!");
7
8 Console.ReadKey();
9 }
10
11 ///The left side operand for an arithmetic operation
12 static int Operand1 { get; set; }
13
14 ///The right side operand for an arithmetic operation
15 static int Operand2 { get; set; }
16
17 ///<summary>Adds two integers and return the result</summary>
18 ///<returns>the difference between the two operands</returns>
19 static int Add(int operand1, int operand2)
20 {
21 return operand1 + operand2;
22 }
23
24 ///<summary>Subtract two integers and return the result</summary>
25 ///<returns>the difference between the two operands</returns>
26 static int Subtract(int operand1, int operand2)
27 {
28 return operand1 - operand2;
29 }
30}Then we can get IntelliSense when we want to use any of the class members
Wrap Up
XML Documentation comments can be extremely useful in helping you, or other programmers who will use your code, to understand the code better. We looked at three recommended tags with a class containing members that utilised them. You saw how it provides IntelliSense information from these comments.
Use XML documentation as much as possible and give more meaning to your code. See the C# documentation for more recommended tags.