如何在 C# XML 文档中引用带有自定义链接文本的参数？

Question

我正在使用 XML 注释记录一些 C# 函数，并且我想使用替代文本而不是参数名称来引用参数。这是我想要实现的目标的示例：

/// <summary>
/// Calculates foo using <paramref name="bar">the provided bar value</paramref>.
/// </summary>
/// <param name="bar">The bar value.</param>
/// <returns>The calculated foo value.</returns>
public double Foo(double bar)
{
return foo = bar * 2;
}

在此示例中，我希望文本“提供的条形值”是指向

bar

参数的链接文本。但是，

<paramref>

标签似乎不支持这种方式的自定义链接文本。

有没有办法在 C# XML 文档中实现此目的，或者有任何解决方法来引用带有自定义链接文本的参数？

预先感谢您的帮助。

PS：提供的示例仅供说明之用。我的实际需要是记录一些计算函数，其中参数有时具有很长的描述性名称。我想使用他们的符号来使描述更容易阅读。

Answer 1

不幸的是，在C#中，该标签不支持自定义链接文本。它被设计为按名称引用参数，并且始终使用参数的名称作为链接文本。

但是，要实现文本“提供的栏值”指向栏参数的类似效果，您需要通过以不同方式构造句子或以让读者清楚的方式突出显示参数名称来进行妥协。

您可以重写句子以明确包含参数名称，同时仍然保持清晰，如下所示：

/// <summary>
/// Calculates foo using the provided value of <paramref name="bar"/>.
/// </summary>
/// <param name="bar">The bar value.</param>
/// <returns>The calculated foo value.</returns>
public double Foo(double bar)
{
    return foo = bar * 2;
}