How to Reference Generic Classes and Methods in Xml Documentation

How to reference generic classes and methods in xml documentation

To reference the method:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.

Reference the Generic Type in an XML Documentation comment

Can anybody explain me what I am doing wrong?

It's hard to say, as your question lacks some important details. But, I suspect the code you didn't include in your post looks something like this:

/// <inheritdoc/>
class DeveloperController : IApiController<Developer>
{
    public Task<ActionResult<Developer>> Get(int id) { /* ... */ }
}

and that when you view the Intellisense, you are viewing with a variable where the type is DeveloperController, and not IApiController<Developer>.

The problem is that when the <inheritdoc/> markup inherits the XML comments from the original generic class, the <typeparameterref/> element necessarily still refers to the containing type's type parameter, and there is none. It only has the XML comment itself at that point, not the type parameter that was used to construct the generic class.

So, for example, in the following code:

IApiController<Developer> o1 = ...;
DeveloperController o2 = o1;

o1.Get(1);
o2.Get(1);

Intellisense will be able to tell you the actual type parameter when you hover over o1.Get(1), but not when you hover over o2.Get(1).

Note that if the DeveloperController type were itself generic and its type parameter were used for the declaration of the interface inheritance and of course the implementation, then Intellisense would have direct access to the generic type parameter and it would show what you expect. Of course, making that type generic is probably not compatible with your design, so that doesn't really help in this case. But it's worth keeping in mind for other scenarios.

It's also worth keeping in mind this limitation of <typeparameterref/>, because if you had yet another scenario, where the DeveloperController class was generic, but its type parameter was not used for the interface, but instead for some other generic aspect of the class, and calling code used a different type for that type parameter from the one used for the interface, Intellisense would display the wrong type.

For example, you had:

/// <inheritdoc/>
class DeveloperController<T> : IApiController<Developer>
{
    public Task<ActionResult<Developer>> Get(int id) { /* ... */ }
}

and then you used the DeveloperController<T> class with a type parameter of bool, Intellisense would display "Returns Entity with Id = id of Class bool."

Obviously, this is not ideal and in fact I would consider it a bug, however understandable it might be.

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

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.

Reference generic parameter in C# xml documentation comment

With CodingK0ala's link I finally were able to resolve it, even though I looked in the article before and did not find the answer then.

<see cref="MethodName(IEnumerable{string})"/>

Thanks.

EDIT: Actually I don't know what seemed so incomprehensible about it then. :)

How to refer to an extension method of a generic class in XML comments

You were close. The extension method belongs to the Enumerable class. Try:

<see cref="Enumerable.SingleOrDefault{TSource}(IEnumerable{TSource})"/>

---

Related Topics