What is compiler warning CS1723 "XML comment has cref attribute 'T' that refers to a type parameter" all about?

3004 views c#
3

Given this code:

/// <summary>
/// Implementations represent a configuration with a specific data 
/// type <see cref="T"/> that can be used by this application.
/// </summary>
internal interface IConfiguration<T>
{
}

I'm getting a compiler warning CS1723 on T inside the see cref XML element:

XML comment has cref attribute 'T' that refers to a type parameter

MS Docs is completely useless in this case. Why should I care about this warning? What is the reason for it?

answered question

I think the <see cref=""> tags are designed to point another interface, class or other such thing. Here you are pointing to a type called 'T' which probably doesn't exist so its telling you that your documentation is wrong

<see/> denotes a link to another code entity. Where to you expect this link to point to?

2 Answers

8

cref is meant to point to an actual type (eg as a hyperlink in the generated docs). A type parameter doesn't make any sense in this place since it is not known beforehand what type is going to be used.

To document type parameters use

<typeparamref name="name"/>

posted this

Have an answer?

JD

Please login first before posting an answer.