是否有一种有效的方法来处理 Visual Studio 中重复的 XML 注释 C# 代码

Question

我使用 Visual Studio 已经有几年了，我们一直只是手动为我们的 C# 代码编写所有 XML cmets。

但最近我认识到需要一种方法来集中维护某些 XML cmets，因为它们在我们的代码中重复多次。

例如，我们将有几个方法接受相同的参数，因为它们按顺序相互调用，传递变量。

或者我们将在多个完全不同的位置使用相同的参数（例如版本处理的搜索日期）。

/// <summary>
/// Get data by searchdate
/// </summary>
/// <param name="searchdate">The date to use while fetching the data</param>
public void MethodX(DateTime searchDate)
    // fetch something from somewhere by date
    var y = MethodY(searchDate);
}

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <param name="searchdate">The date to use while fetching the data</param>
public void MethodY(DateTime searchDate)
    // fetch something more from somewhere else by date
}

我们不能将它们存储在资源文件中，因为您不能在 XML 标记中使用代码（至少我认为我不能）。

有没有一种有效的方法来存储和维护我们的 XML cmets 中的这些重复部分？

Answer 1

如果您只想在一个地方添加 XML 注释并在其他地方重复使用，您可以使用 <inheritdoc> XML 文档标签。此标签受到 VS Intellisense 以及可以从您的 cmets 生成文档的工具的尊重，例如 VSdocman（我是它的作者）。

您的代码可能如下所示：

/// <summary>
/// Get data by searchdate
/// </summary>
/// <param name="searchDate">The date to use while fetching the data</param>
public void MethodX(DateTime searchDate)
{
    // fetch something from somewhere by date
    MethodY(searchDate);
}

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <param name="searchDate"><inheritdoc cref="MethodX"/></param>
public void MethodY(DateTime searchDate)
{
    // fetch something more from somewhere else by date
}

MethodY 中不带 param 标记的 inheritdoc 的替代版本：

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <inheritdoc cref="MethodX" select="/param[name='searchDate']"/>
public void MethodY(DateTime searchDate)

如果您想将您的 XML cmets 存储在一个中心位置，您可以将它们保存在一个外部 XML 文件中，并使用<include> XML doc 标签链接到它们。

类似的东西（未测试）：

/// <summary>
/// Get some more data by searchdate
/// </summary>
/// <include file="myXmlComments.xml" path="[@name='MyClass.MethodX']/param[name='searchDate']"/>
public void MethodY(DateTime searchDate)