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

Question

Writing some XML documentation for a predicate helper class. But I can\'t figure out I can refer to an Expression> without getting a synta

Answer 1

// Use "&lt;" instead of "<" symbol and "&gt;" instead of ">" symbol.

// Sample:

<see cref="Expression&lt;Func&lt;T, bool&gt;&gt;"/>

Answer 2

Don't use an empty see element (<see cref="..." />). Instead, put text inside the see element

<see cref="IEnumerable{T}">IEnumerable</see>&lt;<see cref="..."/>$gt;

Answer 3

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.

Answer 4

What exactly would you like it to link to?

There's no such thing in the documentation as a Expression<Func<T>>, so obviously a link to that would not work.

You can link to Expression<TDelegate> because that exists.

As for what works or not, neither of the following works in Visual Studio 2008 / .NET 3.5 for me:

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

But this works:

/// <see cref="Expression{T}"/>.

so apparently the generic type parameter doesn't have to the same as the one in the declaration.

Answer 5

I'm running into this now, as I have a function that returns a List<List<byte>>. Yeah, it's ugly, but I didn't write it. Standard disclaimer, I know.

Anyway, in VS 2017 with R# Ultimate 2017.1, this doc comment...

<returns><see cref="List{List{Byte}}" /> of split frames</returns>

...gives me a syntax error. However, this...

<returns><see><cref>List{List{byte}}</cref></see> of split frames</returns>

...does not. Eeeenteresting.

Still ugly? Yes.

As ugly? I think it's less horrible than using < and > myself....