C# – Referring to a generic type of a generic type in C# XML documentation

cgenericsresharpervisual-studio-2008xml-documentation

Writing some XML documentation for a predicate helper class. But I can't figure out I can refer to an Expression<Func<T, bool>> without getting a syntax error. Is it even possible? I have tried this:

<see cref="Expression{Func{T, bool}}"/>

But I get a red squiggly line under {T, bool}}. This works though:

<see cref="Expression{TDelegate}"/>

Anyone have a clue?

Update:

The answer that was given (and I accepted) seemingly did work. But now I have started to get a lot of warnings about stuff not being able to resolve. I have a class called ExpressionBuilder<T> which works with Expression<Func<T, bool>> a lot. So I of course want to refer to that in my XML comments.

I have tried both versions that I know about:

<see cref="Expression&lt;Func&lt;T, Boolean&gt;&gt;"/>
<see cref="Expression{Func{T, Boolean}}"/>

But neither work. (And on the last one, ReSharper puts a blue squiggly under {T,Boolean}} I get two warnings under compilation everywhere I have used it which says that:

  1. XML comment on 'blah blah' has cref attribute 'Expression>' that could not be resolved
  2. Type parameter declaration must be an identifier not a type. See also error CS0081.

Have the same issue somewhere I tried to refer to Range<Nullable<DateTime>> (Range<DateTime?> didnt work either. Both with { } and with &lt; &gt;)

Am I not supposed to refer to these kinds of generics?

Best Answer

There seems to be no way to refer to a generic of a generic in XML documentation, because actually, there's no way to refer to a generic of any specific type.

Lasse V Karlsen's answer made it click for me:

If you write <see cref="IEnumerable{Int32}" />, the compiler just uses "Int32" as the type parameter name, not the type argument. Writing <see cref="IEnumerable{HelloWorld}" /> would work just as well. This makes sense because there is no specific page in MSDN for "IEnumerable of int" that your documentation could link to.

To document your class properly, I think you'd have to write something like:

<summary>
Returns an <see cref="IEnumerable{T}" /> of <see cref="KeyValuePair{T,U}" /> 
of <see cref="String" />, <see cref="Int32" />.
</summary>

I hope you like text.

Related Topic