M B A R K's Blog
The XML Documentation in C#

The XML Documentation in C#

M B A R K's photo
M B A R K
·

8 min read

Table of contents

Introduction

XML documentation is a powerful feature in C# that allows developers to add detailed documentation to their code. This documentation can be used by other developers who are working with the code, as well as by tools such as Visual Studio and the C# compiler.

How it Works

When a developer writes a comment in C# that starts with three slashes (///), that comment is considered to be part of the XML documentation. The comment must be placed directly above the element that it is documenting, such as a class, method, or property.

For example, the following code shows a class with a method that is documented using XML documentation:

/// <summary>
/// This is the MyClass class.
/// </summary>
public class MyClass
{
    /// <summary>
    /// This is the MyMethod method.
    /// </summary>
    /// <param name="value">The value to use.</param>
    /// <returns>The result of the operation.</returns>
    public int MyMethod(int value)
    {
        return value * 2;
    }
}

In this example, the MyClass class and the MyMethod method both have XML documentation comments. The <summary> tag is used to provide a brief overview of the class or method, while the <param> and <returns> tags are used to provide more detailed information about the method's parameters and return value.

Using the Generated Documentation

When the C# compiler encounters XML documentation comments, it generates a separate XML file that contains the documentation. This file has the same name as the source code file, but with a .xml extension.

For example, if the source code file is MyClass.cs, the generated documentation file would be MyClass.xml.

This generated documentation file can then be used by other tools, such as Visual Studio, to provide IntelliSense information and generate documentation for the code.

Examples

Here are some examples of how XML documentation can be used in C#:

Documenting a Class

/// <summary>
/// Represents a person.
/// </summary>
public class Person
{
    /// <summary>
    /// The person's first name.
    /// </summary>
    public string FirstName { get; set; }

    /// <summary>
    /// The person's last name.
    /// </summary>
    public string LastName { get; set; }
}

In this example, the Person class is documented with a brief overview of what it represents. The class's properties, FirstName and LastName, are also documented to provide information about their purpose.

Documenting a Method

/// <summary>
/// Calculates the area of a rectangle.
/// </summary>
/// <param name="width">The width of the rectangle.</param>
/// <param name="height">The height of the rectangle.</param>
/// <returns>The area of the rectangle.</returns>
public int CalculateRectangleArea(int width, int height)
{
    return width * height;
}

In this example, the CalculateRectangleArea method is documented with a brief overview of what it does, as well as detailed information about its parameters and return value.

Documenting a Property

/// <summary>
/// The current temperature in Fahrenheit.
/// </summary>
public double Temperature { get; set; }

In this example, the Temperature property is documented with information about its purpose, which is to represent the current temperature in Fahrenheit.

Documenting a Constructor

/// <summary>
/// Initializes a new instance of the MyClass class.
/// </summary>
/// <param name="value">The value to use.</param>
public MyClass(int value)
{
    this.Value = value;
}

In this example, the constructor of the MyClass class is documented with a brief overview of its purpose and information about its parameter.

Documenting an Enumeration

/// <summary>
/// Enumerates the possible colors.
/// </summary>
public enum Colors
{
    /// <summary>
    /// The color red.
    /// </summary>
    Red,

    /// <summary>
    /// The color green.
    /// </summary>
    Green,

    /// <summary>
    /// The color blue.
    /// </summary>
    Blue
}

In this example, the Colors enumeration is documented with a brief overview of its purpose, and each enumeration value is also documented with information about its meaning.

XML Documentation Tags

XML documentation in C# uses a variety of tags to provide different types of information about the code. Some of the most commonly used tags include:

<summary>

The <summary> tag is used to provide a brief overview of the element that it is documenting. This tag should be used for classes, methods, properties, and other elements that need a brief description.

For example:

/// <summary>
/// This is the MyClass class.
/// </summary>
public class MyClass
{
    /// <summary>
    /// This is the MyMethod method.
    /// </summary>
    public void MyMethod() { }
}

<param>

The <param> tag is used to provide information about the parameters of a method or constructor. This tag should be used for each parameter of the element, and should include the parameter's name and a brief description.

For example:

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <param name="value">The value to use.</param>
public void MyMethod(int value) { }

<returns>

The <returns> tag is used to provide information about the return value of a method or property. This tag should be used to describe the type and purpose of the returned value.

For example:

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <returns>The result of the operation.</returns>
public int MyMethod() { return 0; }

<typeparam>

The <typeparam> tag is used to provide information about the type parameters of a generic class or method. This tag should be used for each type parameter, and should include the type parameter's name and a brief description.

For example:

/// <summary>
/// This is the MyGenericMethod method.
/// </summary>
/// <typeparam name="T">The type of the parameter.</typeparam>
public void MyGenericMethod<T>() { }

<exception>

The <exception> tag is used to provide information about the exceptions that may be thrown by a method. This tag should be used for each exception that the method may throw, and should include the exception's type and a brief description.

For example:

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <exception cref="ArgumentException">Thrown when the value is invalid.</exception>
public void MyMethod(int value) { }

<remarks>

The <remarks> tag is used to provide additional information about an element. This tag can be used to provide additional details or examples, or to provide information that doesn't fit in the other tags.

For example:

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <remarks>
/// This method should only be used for positive values.
/// </remarks>
public void MyMethod(int value) { }

<see>

This tag is used to create a link to another element in the documentation. For example, if you want to link to another class or method, you can use the <see> tag.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <see cref="MyClass.MyOtherMethod"/>
public void MyMethod() { }

<seealso>

This tag is used to create a link to a related element in the documentation. For example, if you want to link to another class or method that is related to the current element, you can use the <seealso> tag.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <seealso cref="MyClass.MyOtherMethod"/>
public void MyMethod() { }

<list>

This tag is used to create a list of items within the documentation. This is useful when you want to provide a list of related items or information.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <list type="bullet">
/// <item>The first item.</item>
/// <item>The second item.</item>
/// </list>
public void MyMethod() { }

Additionally, there are also several other tags that can be used to enhance the documentation and make it more informative.

<code>

This tag is used to highlight specific pieces of code within the documentation. This is useful when you want to show an example of how to use a particular method or class.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <example>
/// <code>
/// int result = MyMethod(5);
/// Console.WriteLine(result);
/// </code>
/// </example>
public int MyMethod(int value) { return value*2; }

<para>

This tag is used to separate different paragraphs of text within the same tag. This is useful when you want to organize the information in a more readable way.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <remarks>
/// <para>This method should only be used for positive values.</para>
/// <para>The result of this method will be the input value multiplied by 2.</para>
/// </remarks>
public int MyMethod(int value) { return value*2; }

<paramref>

This tag is used to refer to a specific parameter within the documentation. This is useful when you want to refer to a parameter multiple times within the same tag.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <param name="value">The value to use.</param>
/// <remarks>
/// <para>The value passed to <paramref name="value"/> should only be positive</para>
/// </remarks>
public int MyMethod(int value) { return value*2; }

<typeparamref>

This tag is used to refer to a specific type parameter within the documentation. This is useful when you want to refer to a type parameter multiple times within the same tag.

/// <summary>
/// This is the MyGenericMethod method.
/// </summary>
/// <typeparam name="T">The type of the parameter.</typeparam>
/// <remarks>
/// <para>The type passed to <typeparamref name="T"/> should implement IComparable interface</para>
/// </remarks>
public void MyGenericMethod<T>() where T : IComparable {}

<example>

This tag is used to provide an example of how to use a particular element. The example can include code, explanations, or both.

/// <summary>
/// This is the MyMethod method.
/// </summary>
/// <example>
/// <code>
/// int result = MyMethod(5);
/// Console.WriteLine(result);
/// </code>
/// The output will be 10.
/// </example>
public int MyMethod(int value) { return value*2; }
C#documentation