How to display general parameter arguments in xml documentation

Question

I can refer to 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 / generated help file says Func<TResult> .

Answer 1

In the first example, you specify the cref attribute type as 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 this type: Func<TResult> . It is easy to find and link. Note that this creates one link to one type.

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

You probably want to create a link that uses two links for two types, for example, on the Enumerable.Sum help page. For this method

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

they documented the choice of the parameter using two links:

Type: System.Func <TSource, Int32a →

Here they refer to two types, not one. One of the links looks like this is a reference to the System.Func delegate System.Func (which again is not a type with the documentation we can point to), but in fact it points to the System.Func<T,TResult> delegate documentation. Another link is System.Int32 .

You can do this if you get more formal. Xml passes the compiler check and does not change if you use

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

However, I do not know how this will be displayed in most templates. This is what is used to document the source code of the Entity Framework. For an example (which doesn't display well), you can look at the documentation for System.Data.Entity.Core.Common.CommandTrees.ExpressionBuilder namespace .

I also saw how this was done with

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

Again, ignoring the template to render it beautifully and only for xml, this creates markup that passes compiler syntax checking. You might be lucky if you change this from xml to create your actual documentation.