如何在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>。

- Julian Lettner

Answer 1

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

在第二个示例中，当您查找类型Func<Int32>时，实际上没有文档可以指向该类型。 System命名空间中的类型是通用的并带有参数。您可能不认为它是精确匹配，但解析器假设Int32是您用于类型参数的名称，并且您想要指向它可以轻松在System命名空间中找到的类型。同样，这会产生一个链接到实际上可以在System命名空间中找到的一个类型。

您可能希望创建一个引用，使用两个链接到两个类型，就像在Enumerable.Sum参考页面上所做的那样。对于此方法，

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

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

类型：System.Func<TSource, Int32>

在这里，他们引用了两种类型，而不仅仅是一种。其中一个链接看起来是对委托组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转换为实际文档时，可能会更加顺利。

- Steve Clanton

---

那么我正在尝试的事情没有办法做到吗（也许可以使用其他属性）？ - Julian Lettner

我已经更新了我的答案，展示了如何做你想要做的事情。 - Steve Clanton