Using <param> and <paramref> Tag in C# XML Documentation Comments
Aug 8, 2018 • 3 Minute Read
Introduction
Code documentation describes the intent of a software's code. These includes the intent or description of a class and its members, the parameters and the expected result, or the return value. XML code documentation must immediately precede a user-defined type (such as class, interface or delegate) or its member (such as field, property, method, or event). Documentation 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 XML documentation starts with /// and can contain recommended tags that gives special meaning to the comment. Two of those recommended tags are <param> and <paramref> which we will be looking at in this guide.
Tag
The <param> tag is used to describe parameters for a method or constructor. Let's say we have a method that adds two numbers together and returns the result as follows
/// <param name="operand1">the left side operand.</param>
/// <param name="operand2">the right side operand.</param>
static int Add(int operand1, int operand2)
{
return operand1 + operand2;
}
The name attribute contains the name of the parameter to describe, while the description is contained within the opening and closing of the tag. With this definition whenever the IntelliSense reads this method, it shows the description of the parameters.
Tag
The <paramref> tag is used to indicate that a word is a parameter. There are times when you might be describing what a method does within the <summary> or <remarks> tag, and you want to make a reference to a parameter in the description. This is where the <paramref> tag can be utilized. This way, if you generate an XML documentation file for your project, this file can be processed to format this word in a distinct way.
Applying it to the Add method will look like the following:
/// <summary>This method adds <paramref name="operand1"/> and <paramref name="operand2"/>.</summary>
/// <param name="operand1">the left side operand.</param>
/// <param name="operand2">the right side operand.</param>
static int Add(int operand1, int operand2)
{
return operand1 + operand2;
}
Similar to the <param> tag, the name attribute is the parameter name which gets displayed alongside the description within the <summary> tag.
Wrap Up
Documentation comments can be extremely useful in helping you, or other programmers who will use your code, to understand your code better. In our example, the code conveys that the first parameter will be used as the left side operand, which could help tell how the method does its calculation. Use XML documentation as much as possible and give more meaning to your code. See the C# documentation for more recommended tags.
