17

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?

Community
  • 1
  • 1
rory.ap
  • 34,009
  • 10
  • 83
  • 174
  • I think the `` 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 – Dave Nov 05 '18 at 15:57
  • 1
    denotes a link to another code entity. Where to you expect this link to point to? – Klaus Gütter Nov 05 '18 at 15:58

2 Answers2

27

To reference a type parameter, use <typeparamref name="T" />.

/// <summary>
/// Implementations represent a configuration with a specific data 
/// type <typeparamref name="T" /> that can be used by this application.
/// </summary>
internal interface IConfiguration<T>
{
}
Matt Johnson-Pint
  • 230,703
  • 74
  • 448
  • 575
7

see cref (cross reference) 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"/>

adjan
  • 13,371
  • 2
  • 31
  • 48