使用<inheritdoc/>有什么好处？

Question

过去，在 .NET 代码中，我认为有必要指定

<inheritdoc/>

才能从继承成员的

<summary>

注释中获取描述（例如）。

现在，至少在 Visual Studio 中，是否使用

<inheritdoc/>

似乎没有区别。我们总是看到继承的描述。 这里讨论了这个问题。

由于 Visual Studio 没有明显的好处，我倾向于删除

<inheritdoc/>

，或者至少不需要指定。

但是，使用它有什么好处吗？例如，我在 Visual Studio 中缺少什么吗？或者当前是否有使用它的文档工具？

Answer 1

<inheritdoc>

标签还是非常需要的。我经常使用它。它允许您从未继承的成员继承注释或注释部分。

例如：

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) { }
}   

是的，文档工具将从中受益，包括我的VSdocman。但上面的示例也适用于 Intellisense。

Answer 2

由于 Visual Studio 没有明显的好处，我的倾向是应该删除它，或者至少不需要指定。

无论

<inheritdoc/>

为空，我都同意。根据 Peter 的回答，如果您想通过 使用

cref

和

path

属性 重用不是通过类型系统继承的文档，这仍然是一个有用的标签。例子有：

• 从异步方法的同步版本继承文档。
• 在方法和该方法的

  Command

  类表示之间共享文档。

但是，当它是空白的时候，它就没用了。

从 Visual Studio 2019 更新 16.4 开始：

没有 XML 文档的方法现在可以自动从其重写的方法继承 XML 文档。将光标放在实现已记录的接口方法的未记录的方法上。然后，Quick Info 将通过接口方法显示 XML 文档。

对于继承类型，当不为空或者添加了自定义文档时，是有问题的。

如果您倾向于修改继承类型的文档，这可能表明您违反了里氏替换原则（LSP）。

有效的例外可能是当您想要使用针对具体类型定制的语言时，或者当然是为了突出显示 LSP 违规行为。

因此，我个人不相信添加

<inheritdoc/>

可以确保缺乏文档并不是疏忽这一可能的论点；这种情况下的文档应该不鼓励！

不幸的是，启用

DocumentationFile

会导致编译器警告CS1591。

如果您的项目设置为将警告视为错误（强烈推荐），这意味着除非您抑制此警告，否则您的构建将会失败。

我认为最好抑制此警告，因为无法通过

DocumentationFile

选项更精细地配置文档要求。

更重要的是，我认为该警告是一个 bug，因为所有添加

<inheritdoc/>

所做的都是向 XML 输出添加完全相同的标签（即，它不会复制文档）。随后，Visual Studio IntelliSense 使用它，它支持以任何方式显示开箱即用的基本类型文档。

相反，依赖第三方工具，例如 DocFX、Sandcastle、Doxygen 或 StyleCop 规则，这些工具有望有更多选项来执行更合理的文档要求。我尚未研究这些可配置的程度，但乍一看它们是可配置的，并且您可以期待在后续版本中出现更快速发展的选项。

一个显着的好处是能够使用

Answer 3

扩展接口或超类的文档。

只需在您想要继承的每个特定部分中包含 

<inheritdoc/>

，然后包含您的附加备注。

这是 

System.IEquatable<T>

的

Equals(T? other)

 方法的示例：

public class BinaryTreeNode : IEquatable<BinaryTreeNode> {
    // Properties and other Methods...

    /// <summary>
    /// <inheritdoc/>
    /// <para>
    /// Specifically for the <see cref="BinaryTreeNode"/>, this indicates that the current and all descendant nodes are equal.
    /// </para>
    /// </summary>
    /// <param name="other"><inheritdoc/></param>
    /// <returns><inheritdoc/></returns>
    public bool Equals(BinaryTreeNode? other)
    {
        // Implementation...
    }
}