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

Question

这根本不是什么大问题,但如果解决了,那将会非常有用.

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

所以我想知道是否有一种方法可以将注释存储在一个地方(比如变量),我可以简单地引用它.这样,一个变化将反映在所有相关的公司中.

这是一个例子:

    /// <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

是的，您可以通过使用带有属性的标记<inheritdoc>cref来执行此操作（在 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);
    }

Answer 2

根据这些规范：

http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

XML 注释没有固定的标准；该页面上显示的只是“推荐”。在推荐的标签中，没有这个功能。然而，XML 文档工具很乐意接受以下内容而不发出任何警告：

/// <summary id="30">foo</summary>
void bar();

/// <summary id="30"/>
void bar(int baz);

这对您是否有用取决于您对编译器生成的 XML 文件的具体操作。不幸的是，诸如 Intellisense（代码完成和 IDE 内工具提示等）之类的东西。不会用它做任何事。

编辑：尝试一下，如http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx<include>中所述。它有点重量级，因为它需要一个单独的文件，但如果您的文档很大，那么它可能是值得的。