Any benefit to using ?

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?

I often have a StyleCop analyzer active in my project. It complains about undocumented public code (as it should) and shuts up when I add `///` (on overridden or interface-implementing methods only, of course) — Hans Keﬆing, Nov 28 '22 at 13:30

score 1 · Answer 1 · answered Nov 28 '22 at 12:55

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.

Any benefit to using ?

1 Answers1