Any benefit to using <inheritdoc/>?

Question

In the past, in .NET code I believe it was necessary to specify <inheritdoc/> in order to get the description from the <summary> comment of an inherited member (for example).

Now, in Visual Studio at least, there appears to be no difference whether or not <inheritdoc/> is used. We always see the inherited description. This is discussed here.

Since there is no apparent benefit in Visual Studio, my inclination is that <inheritdoc/> should be removed, or at least not required to be specified.

However, is there some benefit to using it anyway? For example, is there something I'm missing in Visual Studio? Or are there current documentation tools that use it?

Answer 1

The <inheritdoc> tag is still very needed. I use it often. It allows you to inherit comments or comment parts also from not inherited members.

For example:

public class Class1
{
    /// <summary>
    /// This is a method in a base class.
    /// </summary>
    /// <param name="specialCode">The special code with the following allowed values:<br/>
    /// "VAL_1"<br/>
    /// "VAL_2"<br/>
    /// </param>
    /// <remarks>
    /// <para>Bla bla.</para>
    /// <para id="algorithm">
    /// This is a very long description of some algorithm.
    /// ...
    /// </para>
    /// </remarks>
    public virtual void Method1(string specialCode) { }


    // Inherit parameter and one paragraph from remarks.
    // Not from an inherited method.

    /// <summary>
    /// Another method in a base class.
    /// </summary>
    /// <param name="specialCode">
    /// <inheritdoc cref="Method1(string)"/>
    /// </param>
    /// <remarks>
    /// This method uses an algorithm described below.
    /// <inheritdoc cref="Method1(string)" path="/remarks/para[@id='algorithm']"/>
    /// </remarks>
    public void Method2(string specialCode) { }
}


public class Class2 : Class1 {

    // inherit all except for the summary.

    /// <summary>
    /// This is an overridden method.
    /// </summary>
    /// <inheritdoc/>
    public override void Method1(string specialCode) { }
}   

And yes, the documentation tools will benefit from it, including my VSdocman. But the example above will work with Intellisense as well.

Answer 2

Since there is no apparent benefit in Visual Studio, my inclination is that should be removed, or at least not required to be specified.

Wherever <inheritdoc/> is blank, I agree. As per Peter's answer, this is still a useful tag in case you want to reuse documentation which isn't inherited through the type system, by using the cref and path attributes. Examples are:

• Inheriting documentation from the synchronous version for an asynchronous method.
• Sharing documentation between a method, and a Command class representation of said method.

But, when it's blank, it's useless.

Starting from Visual Studio 2019 Update 16.4:

Methods that have no XML documentation can now automatically inherit XML documentation from the method it is overriding. Place your cursor over the undocumented method that implements a documented interface method. Quick Info will then display the XML documentation from the interface method.

For inheriting types, when it isn't blank or custom documentation is added, it's questionable.

If you are inclined to modify the documentation for inheriting types, this can be an indication you are violating the Liskov Subtitution Principle (LSP).

Valid exceptions could be when you can want to use language tailored to the concrete type, or of course, to highlight LSP violations.

So, I personally don't buy into the likely argument that adding <inheritdoc/> makes sure the lack of documentation isn't oversight; documentation in this case should be discouraged!

Unfortunately, enabling DocumentationFile causes the compiler warning CS1591.

If you have your project set up to treat warnings as errors (highly recommended), this means unless you suppress this warning, your build will fail.

I would argue it's best to suppress this warning, as there is no way to configure documentation requirements more granularly through the DocumentationFile option.

More so, I consider the warning a bug, since all adding <inheritdoc/> does is add the exact same tag to the XML output (i.e., it doesn't copy over documentation). Subsequently, this gets used by Visual Studio IntelliSense, which supports showing documentation of base types out of the box either way.

Instead, rely on third-party tools such as DocFX, Sandcastle, Doxygen, or StyleCop rules, which hopefully have more options to enforce more reasonable documentation requirements. I have not yet looked into the degree to which these are configurable, but at a glance they are, and you can expect more quickly evolving options in subsequent releases.