c# - 如何在 xml 文档中显示通用参数参数

Question

我可以像这样引用泛型类型/方法定义:

/// <summary>
/// Takes a <see cref="Func{T}"/>.
/// </summary>
public void Method<T>(Func<T> func) { }

但是这不起作用:

/// <summary>
/// Takes a <see cref="Func{Int32}"/>.
/// </summary>
public void Method(Func<int> func) { }

ReSharper/生成的帮助文件说 Func<TResult> .

Answer 1

在第一个示例中，您指定了 cref 的类型作为类型的属性:Func<T> .这与 System 中的类型完全匹配命名空间。我们需要为该类型创建一个文档链接: Func<TResult> .它很容易找到并链接到。请注意，这会产生一个指向一种类型的链接。

在第二个示例中，当您查找类型 Func<Int32> 时，这实际上不是您可以指向的文档类型。 System 中的类型namespace 是通用的并带有一个参数。您可能不会将其视为完全匹配，但解析器会假设 Int32是您用于类型参数的名称，并且您希望指向它可以在 System 中轻松找到的类型命名空间。同样，这会生成一个指向您实际上可以在 System 命名空间中找到的一种类型的链接。

您可能想要创建一个引用，它使用指向两种类型的两个链接，就像在 Enumerable.Sum 上所做的那样引用页。对于这种方法，

public static int Sum<TSource>(
    this IEnumerable<TSource> source,
    Func<TSource,int> selector
)

他们使用两个链接记录了参数选择:

Type: System.Func<TSource, Int32>

在这里，它们引用了两种类型，而不是一种。其中一个链接看起来像是对委托(delegate)组 System.Func 的引用(这又不是我们可以指向的带有文档的类型)，但它实际上指向 System.Func<T,TResult>代表的文件。另一个链接是System.Int32 .

如果你变得更正式，你可以这样做。 xml通过编译器验证，如果使用

则不会改变

<see cref="T:System.Func{T:System.Int32}"/>

但是，我不知道在大多数模板中会如何显示。它用于记录 Entity Framework 源代码。例如(显示效果不佳)，您可以查看 System.Data.Entity.Core.Common.CommandTrees.ExpressionBuilder namespace 的文档.

我也看到了

<see cref="T:System.Func &lt; T:System.Int32 &gt;"/>

同样，忽略模板以很好地显示它并仅通过 xml，这会生成通过编译器语法验证的标记。当您将其从 xml 转换为创建实际文档时，您可能会更幸运。