Reference the Generic Type in an XML Documentation comment

Question

I have a interface like this:

public IApiController<T> where T: IEntity
{
    /// <summary>
    /// Returns Entity with Id = <paramref name="id"/> of Class <typeparamref name="T"/>.
    /// </summary>
    public Task<ActionResult<T>> Get(int id);
}

In my comment I want to reference T, so when I have a DeveloperController that implements IApiController<Developer> the Intellisense comment says:

"Returns Entity with Id = id of Type Developer"

but I only get the following comment:

"Returns Entity with Id = id of Type T"

Can anybody explain me what I am doing wrong?

Answer 1

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.