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

Question

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

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

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

或者我们将在多个完全独立的位置使用相同的参数(如版本处理的搜索日期)。

/// <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 注释中这些重复的部分？

Answer 1

您可以使用 <inheritdoc> XML doc 标签，如果你想只在一个地方使用你的 XML 注释并在其他地方重用它。 VS Intellisense 以及可以根据您的评论生成文档的工具(例如 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 评论存储在一个中心位置，您可以将它们保存在一个外部 XML 文件中并使用 <include> 链接到它们。 XML 文档标签。

类似(未测试):

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