XML comments

XML documentation comments are a special kind of comment, added above the definition of any user-defined type or member.

Once you enable GenerateDocumentationFile (I did it from the IDE which added this GenerateDocumentationFile element to my .cspoj file) you will need to inheritdoc to derived classes. This is applicable when using a base class or interfaces.

The steps for VS 2017 was properties (from project) -> build -> output -> check XML documentation file

inheritdoc

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/// <summary>
/// Some ISweet related comment
/// </summary>
public interface ISweet
{
    /// <summary>
    /// Some Foo related comment
    /// </summary>
    void Foo();
}

///<inheritdoc/>
public class Sweet : ISweet
{
    ///<inheritdoc/>
    public void Foo()
    {
        // do foo things!
    }
}

cref

The cref attribute in an XML documentation tag means “code reference.”

Link to some code:

1
2
3
4
5
6
7
8
9
10
/// <summary>
/// It does the thing
/// </summary>
/// <remarks>
/// This will link to the `SomeFooClass` class - <see cref="SomeFooClass"/>.
/// </remarks>
public static void Foo()
{
    // do foo things!
}

Its also helpful to link to exceptions, here the constructor links to the class FooValidationException which is a validation execption.

1
2
3
4
5
6
/// <summary>
/// It does the thing
/// </summary>
/// <param name="foo1"></param>
/// <exception cref="FooValidationException"></exception>
public Foo(