Delimiters for Documentation Tags in C#
The use of XML documentation comments requires delimiters. Learn how to use either the single-line delimiter or the multiline delimiter.
Aug 22, 2018 • 5 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. There are various syntaxes for comments in C#. One of these is XML Documentation comments, sometimes called XML comments. They can contain specific XML tags (also known as documentation tags) which can be interpreted and displayed visually by a documentation viewer, after the documentation file has been created. It can be utilized by the IntelliSense feature of Visual Studio and VS Code to show information about a type or member. 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).
The use of XML documentation comments requires delimiters, which tell the compiler where a documentation comment begins and ends. You can either use the single-line delimiter or the multiline delimiter.
Single-line Delimiter
Single-line delimiter begins with triple forward slash /// followed by the comment. If there is a whitespace character following the delimiter, that character is not included in the XML output. It is used by C# project templates and you’ll find it used in documentation examples. With this delimiter, only the content on the same line with the slashes is regarded as a comment.
Below is an example class utilizing single-line delimiter:
class Account
{
/// <summary>Class constructor</summary>
/// <param name="accountNo">the account number.</param>
/// <param name="balance">the account balance.</param>
public Account(string accountNo, int balance)
{
AccountNo = accountNo;
Balance = balance;
}
/// <summary>Customer's account number </summary>
public string AccountNo { get; set; }
public int Balance { get; set; }
}
The code above has documentation comments with single-line delimiter for the class constructor and AccountNo property. The comment for the constructor used the delimiter three times. That’s because the compiler will only read the content on the same line, after the slashes, as comments. The Visual Studio IDE has a feature called Smart Comment Editing that automatically inserts the slashes, inserts the summary and /summary tags, and moves your cursor within these tags after you type the /// delimiter in the Code Editor.
Multiline Delimiter
Multiline delimiter begins with /** and ends with */. It can span many lines, whereby the beginning characters for this delimiter are on one line, the ending characters on another line, and whatever text between them as the comment.
Here’s an example of it used to contain comment on single and multiple line:
class Account
{
/** <summary>Class constructor</summary>
<param name="accountNo">the account number.</param>
<param name="balance">the account balance.</param>
*/
public Account(string accountNo, int balance)
{
AccountNo = accountNo;
Balance = balance;
}
/** <summary>Customer's account number </summary> */
public string AccountNo { get; set; }
public int Balance { get; set; }
}
From the example above, only the part that begins with summary will be processed. The three tag formats produce the same comments. Here are a few formatting rules to keep in mind when using this delimiter.
On the line that contains the /** delimiter, if the remainder of the line is whitespace, the line is not processed for comments.
If the first character after the /** delimiter is whitespace, that whitespace character is ignored and the rest of the line is processed. Otherwise, the entire text on that line after the /** delimiter is processed as part of the comment.
For the lines after the one that begins with the /** delimiter, the compiler looks for a common pattern at the beginning of each line. If the compiler finds a common pattern at the beginning of each line that does not begin with the /** delimiter or the */ delimiter, it ignores that pattern for each line. The pattern can consist of an asterisk followed by optional whitespace(s).
/**
* <summary>Class constructor</summary>
* <param name="accountNo">the account number.</param>
* <param name="balance">the account balance.</param>
*/
public Account(string accountNo, int balance)
{
AccountNo = accountNo;
Balance = balance;
}
On the line that contains the */ delimiter, if there are only white spaces up to the */ delimiter, that line is ignored. Otherwise, the text is processed as part of the comment, subject to the pattern-matching rules described above.
Summary
Documentation comments can be extremely useful in helping you, or other programmers who will use your code, to understand the code better. They can contain certain recommended tags and can be delimited in two ways. With the single-line delimiter or the multiline delimiter. The single-line delimiter is what you’ll find in many examples and it’s the default that comes with the C# project template.
