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 语法，您可以在此处找到更多信息。

如果你小心的话，你可以用它来做一些很棒的事情；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>forTryExample方法时，会显示可以抛出InvalidOperationException. 使用该path属性，我已经对其进行了过滤，因此只有与名称不匹配的节点exception才会被继承。

/: 匹配根节点。

*：匹配任何子节点。

[and ]：匹配任何满足包含谓词条件的节点。

not()：匹配任何不满足括号内表达式条件的节点。

self::exception: 如果当前节点的名称为 ，则匹配当前节点exception。

这导致以下结果：

此外，您可以使用此功能更轻松地显示方法可以抛出的异常，而无需显式键入它们：

/// <summary>
/// Validates a file in some way.
/// </summary>
/// <param name="filePath">A full path to the file to be validated.</param>
/// <inheritdoc cref="File.OpenRead(string)" path="/exception"/>
private static void ValidateFile(string filePath)
{
    using FileStream file = File.OpenRead(filePath);
    // Validation code...
}

上面的这个使用<inheritdoc>将导致方法上的工具提示显示它可以抛出该System.IO.File.OpenRead方法可以抛出的所有异常。请注意确保实际抛出并考虑必要的验证异常。