c# - 有没有办法引用 xml 注释以避免重复它们？

Question

这根本不是什么大问题，但如果解决了确实会很有帮助。

当我重载方法等时，有时 xml 注释完全相同，栏 1 或 2 参数名称。我必须将注释复制/粘贴到每个重载方法中，它们是相同的。然而，有时，如果我更新了其中一个而忘记返回并将它们复制/粘贴到所有其他方法，这可能会导致有关该方法的误导信息。如果有很多重载方法，这可能会非常耗时并且容易出错。

所以我想知道是否有一种方法可以将评论存储在一个地方(如变量)，我可以简单地引用它。这样，一项更改将反射(reflect)在所有相关的社区中。

这是一个例子:

    /// <summary>
    /// Go and do something
    /// </summary>
    public void DoSomething()
    {
        DoSomething(true, "Done something");
    }

    /// <summary>
    /// Go and do something
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    public void DoSomething(bool doIt)
    {
        DoSomething(doIt, "Done something");
    }

    /// <summary>
    /// Go and do something cool
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    /// <param name="doneMessage">message to show once done</param>
    public void DoSomething(bool doIt, string doneMessage)
    {
        if (doIt)
            Console.WriteLine(doneMessage);
    }

如您所见，除了我决定对最后一条进行更正以阅读“去做一些很酷的事情”之外，所有评论都是相同的。现在我必须去改变这也是所有其他方法的评论。

干杯。

Answer 1

是的，您可以使用 the <inheritdoc> tag with a cref attribute 执行此操作(在 VS 2019 16.11 中测试)确保您引用了适当的“父级”重载。

因此在您的示例中，您可以引用具有最多文档的重载，并且智能感知将使用该方法中的所有内容:

    /// <inheritdoc cref="DoSomething(bool, string)"/>
    public void DoSomething()
    {
        DoSomething(true, "Done something");
    }

    /// <inheritdoc cref="DoSomething(bool, string)"/>
    public void DoSomething(bool doIt)
    {
        DoSomething(doIt, "Done something");
    }

    /// <summary>
    /// Go and do something cool
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    /// <param name="doneMessage">message to show once done</param>
    public void DoSomething(bool doIt, string doneMessage)
    {
        if (doIt)
            Console.WriteLine(doneMessage);
    }