c# - 我可以使用 来引用另一个变量的 XML 摘要吗？

Question

当我为我的项目编写函数时，更具体地说，编写它们的 XML 文档注释时，我发现自己经常重复特定参数的注释。这有时会导致误导性文档(因为复制粘贴通常会......)。
这是我想到的一个简单的例子，它代表了真正的问题。

/// <summary>
/// The number that should be doubled
/// </summary>
private static float myNumber = 10f;

/// <summary>
/// Multiplies a number by 2
/// </summary>
/// <param name="number"><inheritdoc cref="myNumber"/></param>
/// <returns>The number multiplied by 2</returns>
private static float MultiplyByTwo(float number)
{
    return number * 2f;
}

在这一行 /// <param name="number"><inheritdoc cref="myNumber"/></param> ，我想要文本“应该加倍的数字”，但它没有显示出来。可能我完全不理解inheritdoc的使用。
我的意思是出现这个。 Visual Studio 应该显示 number 的文档在那个盒子里:

这应该是这样的(无需复制粘贴文本):

那么，有没有办法在 XML 文档注释中引用不同的变量？

Answer 1

在 Visual Studio 16.8.4 中，我可以使用 <inheritdoc>的 path属性来做到这一点。

/// <summary>
/// The number that should be doubled
/// </summary>
private static float myNumber = 10f;
        
/// <summary>
/// Multiplies a number by 2
/// </summary>
/// <param name="number"><inheritdoc cref="myNumber" path="/summary"/></param>
/// <returns></returns>
private static float MultiplyByTwo(float number)
{
    return number * 2f;
}

在 path属性， /选择“根”节点，然后 summary是要在该节点内选择的节点。
结果:
path属性使用 XPath 语法，您可以 find more about here .
如果你小心的话，你可以用它来做一些很棒的事情；我在实现 Try[...] 时经常使用它图案。
例如:

/// <summary>
/// This throws!
/// </summary>
/// <param name="param1">This is a parameter.</param>
/// <param name="param2">This is another parameter!</param>
/// <exception cref="InvalidOperationException"/>
public string ExampleThatCanThrow(int param1, float param2)
{
    throw new InvalidOperationException();
}

/// <summary>
/// This never throws!
/// </summary>
/// <inheritdoc cref="ExampleThatCanThrow(int, float)" path="/*[not(self::exception)]"/>
public bool TryExample(int param1, float param2, out string? result)
{
    result = "No throwing here!";
    return true;
}

通常使用时 <inheritdoc>为 TryExample这样的方法，就说明可以抛出 InvalidOperationException .使用 path属性，我已经过滤了它，所以只有与 exception 的名称不匹配的节点会被继承。 / : 匹配根节点。 * : 匹配任何子节点。 [和 ] : 匹配任何满足所包含谓词条件的节点。 not() : 匹配任何不满足括号内表达式条件的节点。 self::exception : 如果当前节点的名称为 exception，则匹配它.
结果如下: