What is the purpose of remarks tag in c#

Remarks are used for building a documentation file. They are used for more detailed comments, adding supplemental information to the "summary" tag ("summary" tag does show in intellisense).

The generated documentation file will be in XML format.

To generate the documentation file you need to add the "/doc" compiler option. In visual studio you can enable the generation of XML documentation file by:

  1. Right click project name -> properties
  2. Go to Build tab
  3. Enable (check), the XML documentation file option

Many tags in .NET are really leveraged when generating documentation. Perhaps, most popular and one I use is Sandcastle.

Here is one rather old blog post discussing the topic, but you will get the point :

"Most developers I think are aware of the concept of using XML code comments to decorate .NET objects. There are really two benefits: 1) it shows this information in intellisense when you’re consuming the object and 2) you can production component documentation like MSDN."

Source : XML Code Comments and Sandcastle, demystified!


Those tags are used by Visual Studio's IntelliSense to give hints about the classes, functions and properties you create, if they are created properly as follows:

In C# (and with Visual Studio's code editor) this is easily done by typing /// (three forward slashes instead of two) and pressing Return, as shown here:

XmlCommentsAnimation

That will create "XML comments" and add the most common tags for you (for example parameter tags for each parameter of your method).
If the cursor is one line above a class name, it will create a <summary> tag, if it is above a method name, it will create additionally <param> tags for each parameter, and a <returns> tag for the return value.

The immediate benefit you have is that the descriptions you've typed in are shown everywhere (not only in the declaration), you just need to point at the method name or parameter in the source code, as shown here:

XmlCommentsDemoAnimation

Others, like <remarks> are then suggested by IntelliSense while the cursor is inside the /// comments (see example below). As per my knowledge, only <summary> and <param> tags are being used by IntelliSense. If any of those tags contain a cref attribute, you can reference other items (as shown in the example). Newer versions of Visual Studio can show additional tags (see riQQ's comment below this answer).

Additionally, as the other answers are explaining, you can create a XML documentation which can be converted into a hyperlinked document or static html files by using 3rd party tools (such as Sandcastle Help file builder).

Example:

/// <summary>
/// Description what the class does
/// </summary>
public class MyClass
{
    /// <summary>
    /// Description what the function does
    /// </summary>
    /// <param name="param1">Description what the parameter does 
    ///   Optional tags inside param1:
    ///    <c></c> <code></code> <list type=""></list> <paramref name="param1"/>
    ///    <para></para>
    /// </param>
    /// <param name="param2">Description what the parameter does</param>
    /// <returns>Description about the return value</returns>
    public string MyMethod(int param1, string param2)
    {
        return "Some value: " + MyProperty;
    }

    /// <summary>
    /// Description what the property does
    /// </summary>
    /// <see cref="MyMethod(int, string)"/>
    string MyProperty { get; set; }

    // optional tags (valid for class and methods):

    /// <completionlist cref=""/>
    /// <example></example>
    /// <exception cref=""></exception>
    /// <include file='' path='[@name=""]'/>
    /// <permission cref=""></permission>
    /// <remarks></remarks>
    /// <see cref=""/>
    /// <seealso cref=""/>
}