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

【问题标题】：Is there a way of referencing the xml comments to avoid duplicating them?有没有办法引用 xml 注释以避免重复它们？
【发布时间】：2010-06-22 08:59:28
【问题描述】：

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

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

所以我想知道是否有一种方法可以将 cmets 存储在一个地方（如变量），我可以简单地引用它。这样，一个更改将反映在所有相关评论中。

这是一个例子：

    /// <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);
    }

如您所见，所有的 cmets 都是相同的，只是我决定对最后一个进行更正，改为“去做一些很酷的事情”。现在我得去改变这也是所有其他方法 cmets。

干杯。

【问题讨论】：

+1 我一直不敢问这个问题。
@Peter - 公平点，是的，我一直很垃圾。我会整理的，干杯
事情是这样的，人们会停止回答你的问题......你不想要那个:)......或者我错了，你得到了三个答案。

标签： c# .net visual-studio

【解决方案1】：

根据这些规范：

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

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

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

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

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

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

【讨论】：

【解决方案2】：

标准 XML cmets 标签中没有这样的功能。另一方面，Sandcastle Help File Builder 实现了您正在寻找的 <inheritdoc/>。

【讨论】：

【解决方案3】：

如果您有接口，则可以从其他方法中引用其中一种方法，如下所示：

interface ISomeInterface
{
    /// <summary>Handles this and that.</summary>
    void SomeMethod();

    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary>
    /// <param name="i">Param blabla.</param>
    void SomeMethod(int i);
}

class SomeClass : ISomeInterface
{
    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary>
    public void SomeMethod() { }

    /// <summary><see cref="ISomeInterface.SomeMethod(int)"/></summary>
    public void SomeMethod(int i) { }
}

【讨论】：

【解决方案4】：

是的，您可以通过使用 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);
    }

【讨论】：

此外，您还可以将<inheritdoc cref=""/> 与来自导入/引用的程序集/库的类型/成员的引用一起使用，而不仅仅是您自己的用户代码。整洁的。例如：对于我自己的 IHttpClientFactory 扩展方法，我可以使用 /// <inheritdoc cref="Microsoft.Extensions.DependencyInjection.HttpClientFactoryServiceCollectionExtensions.AddHttpClient(IServiceCollection,String)" /> 并且 VS 在我自己的代码的工具提示中显示了引用的 XML 文档。

【解决方案5】：

说我很傻，但是在文档范围内搜索和替换 Go and do something 以及认真使用 Alt+R 或 Alt +A 可能会引起争议。一次编辑 - 好吧，至少输入一次。

@Reinderien 的回答提供了丰富的信息……但在以利用 IntelliSense 或标准处理工具为目标的情况下，帮助不大。

@Peter Lillevold 的回答也提供了丰富的信息，而且我认为它更酷，因为它与 SHFB 对话进行处理......但仍然没有 IntelliSense。

@Paw Baltzersen 的答案可以被使用，而不管是否使用接口并且很诱人……但也没有正确使用 IntelliSense。

我喜欢尽可能避免搜索和替换，但在这里获取 IntelliSense 通常是我的首要考虑。

【讨论】：