How to reference generic classes and methods in xml documentation

Svish_39321 0
Viewed 59093

When writing xml documentation you can use <see cref="something">something</see>, which works of course. But how do you reference a class or a method with generic types? 

public class FancyClass<T>
{
  public string FancyMethod<K>(T value) { return "something fancy"; }
}

If I was going to write xml documentation somewhere, how would I reference the fancy class? how can I reference a FancyClass<string>? What about the method?

For example in a different class I wanted to let the user know that I will return an instance of FancyClass<int>. How could I make a see cref thing for that?

xml-documentation reference generics c#
8 Answers

To reference the method:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.
user_2670 
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

BTW, it was present in the MSDN documentation of .Net Framework 2.0 and 3.0, but it disapeared in the version 3.5

Think_Before_Coding_470010

Here's an answer I gave somewhere else. It will work for classes and methods too.

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
Related