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

Svish_39321 0
Viewed 14448

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?

visual-studio-2008 resharper xml-documentation generics c#
7 Answers

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.

user_10160

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.

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

// Sample:

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

I tried everything on stack overflow to a get results that work under several scenarios. Here's a solution that works for me. (That's subjective concerning anyone else.)

  1. Produces clickable links.
  2. Hovering over identifiers works.
  3. Produces .xml file correctly.
  4. Produces no errors in intellisense.
  5. Works for nullable generic type parameters.
  6. Works in Resharper and it's built-in XML Doc window (Resharper -> Edit -> Show Quick Documentation)
  7. Works in XAM Doc Preview for Atomineer Pro Documentaion Visual Studio Extension.
  8. Works with a generic type of a generic type.

Example #1

  /// <summary>
  ///  This instance field holds a reference to the
  ///  <see cref="ConcurrentDictionary{Decimal, Boolean}"/> as
  ///  <see cref="T:ConcurrentDictionary&lt;decimal, bool?&gt;"/> that contains
  ///  the list of all PDF's that are currently opened and being displayed.
  /// </summary>
  private ConcurrentDictionary<decimal, bool?> openedPdfs = default!;

  Note: 
    The ConcurrentDictionary{Decimal, Boolean} will correctly produce a
    clickable link of ConcurrentDictionary{TKey, TValue} on hovering while
    T:ConcurrentDictionary&lt;decimal, bool?&gt; makes sure the reader gets
    information on what type TKey and TValue are.

Example # 2 (using "T")

  /// <summary>
  ///  This instance field holds a reference to the
  ///  <see cref="ConcurrentDictionary{TKey, TValue}"/> as
  ///  <see cref="T:ConcurrentDictionary&lt;decimal, bool?&gt;"/> that contains
  ///  the list of all PDF's that are currently opened and being displayed.
  /// </summary>
  private ConcurrentDictionary<decimal, bool?> openedPdfs = default!;
user_26230300

I came to use this:

<see cref=""EqualityComparer{T}.Default"">EqualityComparer&lt;<typeparamref name=""TSource""/>&gt;.Default</see>

Applied to your OP here the result:

<see cref="System.Linq.Expressions.Expression{TDelegate}">Expression&lt;Func&lt;<typeparamref name="TSource"/>, Boolean&gt;&gt;.</see>

Here the image of the IntelliSense pop-up:

Render of the comment in VS2019

user_3611770
Related