我可以使用 <inheritdoc cref> 引用另一个变量的 XML 摘要吗？

Question

When I'm writing functions for my project, and more specifically, their XML documentation comments, I find myself repeating the comments for a specific parameter often. This leads to misleading documentation sometimes (as copy pasting usually does...).

This is a simple example I thought of, which represents the real problem.

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

In this line /// <param name="number"><inheritdoc cref="myNumber"/></param>, I would like to have the text "The number that should be doubled", but it's not showing up. Maybe I don't understand the use of inheritdoc completely.

What I mean by showing up is this. Visual Studio should show the documentation of number in that box:

This is what it should look like (without copy pasting the text):

So, is there a way to reference a different variable in XML documentation comments?

Answer 1

在 Visual Studio 16.8.4 中，我可以使用<inheritdoc>'spath属性来执行此操作。

/// <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>通常，当以这种方式使用该方法时TryExample，它会显示它可以抛出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。请注意确保实际抛出并解释了必要的验证异常。