Что такое предупреждение компилятора CS1723 «XML-комментарий имеет атрибут cref 'T', который ссылается на параметр типа" all about?

Question

Учитывая этот код:

/// <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>
{
}

Я получаю предупреждение компилятора CS1723 на T внутри XML-элемента see cref:

XML-комментарий имеет атрибут cref 'T', который ссылается на параметр типа

MS Docs в этом случае совершенно бесполезен. Почему я должен заботиться об этом предупреждении? В чем причина?

Answer 1

see cref (перекрестная ссылка) предназначена для указания на фактический тип (например, как гиперссылка в сгенерированных документах). Параметр типа в этом месте не имеет никакого смысла, так как заранее неизвестно, какой тип будет использоваться.

Для документирования параметров типа используйте

<typeparamref name="name"/>

Answer 2

Вы должны использовать <typeparamref name="T" /> для этого сценария.

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/typeparamref