What is the purpose of remarks tag in c#

Question

I understand that remarks tag is used to provide additional information about the class but it is not displayed in intellisense while hovering / calling that class. I would like to know Where exactly it is useful?

Answer 1

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

Answer 2

The <remarks> ... </remarks> tag is an optional part of the XML comments, being used to provide additional information, for example if there are any known issues you want other developers to be aware of. In newer versions of Visual Studio the content of this tag is displayed in IntelliSense as well.

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:

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:

You'll have an additional benefit if you're developing Web API functions and use Swagger, then you can reference the XML comments in the Swagger startup code. When you compile and run it, and when the API page is being displayed, then the summaries and parameters are being shown instantly in Swagger - so you can make them part of the API documentation.

Other tags, like <remarks> are being 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>
/// <remarks>
/// This is an example class showing how it works.
/// </remarks>
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=""/>
}

Answer 3

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!

Answer 4

It is like @Dodger wrote. To give you a visual impression, here a sample

Code:

/// <summary>A <see cref="MonitorGroup"/> device.</summary>
/// <remarks>If not created with belonging new <see cref="Decoder"/> the properties for <see cref="MonitorGroup.Decoder"/>
/// and <see cref="MonitorGroup.MonitorNumber"/> are <c>null</c>.
/// <para>Refactoring necessary 
/// <list type="bullet">
/// <item><description>a MonitorGroup can connect to several decoders</description></item>
/// <item><description>a MonitorGroup can be connected to several monitors.</description></item>
/// </list>
/// a MonitorGroup can connect to several decoders.</para>
/// </remarks>
/// <seealso cref="MonitorGroup" />
public class MonitorGroup : Device<MonitorGroup>

Now in Visual Studio it is displayed like

and the DocFX creates that

Answer 5

As can be read in the C# guide:

The <remarks> tag is used to add information about a type or a type member, supplementing the information specified with <summary>. This information is displayed in the Object Browser window.

So <summary> is for a compact description of the element and <remarks> is for the full description. When writing code, IntelliSense will show the summary, but in the documentation or more detailed views, the remarks content will be shown. Showing the full description with IntelliSense would take a lot of space, and time to read it.