How to display generic parameter arguments in xml documentation

Question

I can reference a generic type/method definition like this:

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

However this does not work:

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

ReSharper / the generated help file says Func<TResult>.

Answer 1

In the first example, you are specifying the type of the cref attribute as a type: Func<T>. This is an exact match for a type in the System namespace. We need to create a link to the documentation for that type: Func<TResult>. It is easy to find and link to. Note that this produces one link to one type.

In the second example, when you look for the type Func<Int32>, that is not really a type with documentation you could point to. The type in the System namespace is generic and takes a parameter. You might not think of it as an exact match, but the parser makes the assumption that Int32 is the name you are using for the type parameter, and that you want to point to the type it can easily find in the System namespace. Again, this produces one link to one type that you actually can find in the System namespace.

You probably want to create a reference that uses two links to two types, like is done on the Enumerable.Sum reference page. For this method,

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

they documented the parameter selection using two links:

Type: System.Func<TSource, Int32>

Here, they have a reference to two types, not one. One of the links looks like it is a reference to the delegate group System.Func(which is again not a type with documentation we can point to), but it actually points to the System.Func<T,TResult> delegate's documentation. The other link is to System.Int32.

You can do this if you get more formal. The xml passes compiler verification and is unchanged if you use

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

However, I don't know how that will display in most templates. It's what is used to document Entity Framework source code. For an example (that does not display nicely), you can look at the documentation for the System.Data.Entity.Core.Common.CommandTrees.ExpressionBuilder namespace.

I have also seen it done with

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

Again, ignoring the template to display it nicely and only going by the xml, this produce markup that passes compiler syntax verification. You might have better luck when you transform this from xml to create your actual documentation.