Как ссылаться на общие классы и методы в xml-документации

TL; DR:

"Как мне сослаться на FancyClass?"

   /// 

"А как насчет FancyClass.FancyMethod(T value)?"

   /// 

"Как я могу ссылаться на FancyClass?"

   /// 
   ///  whose generic type argument is 

Хотя вы можете ссылаться на метод, сигнатура reference которого включает FancyClass (например, как csharp тип параметра), вы не можете напрямую c-sharp ссылаться на такой закрытый xml-documentation универсальный тип. Второй c-sharp пример позволяет обойти это java-generics ограничение. (Это видно, например, на visual-c# MSDN refence page for the static System.String.Concat(IEnumerable) method). :

Комментарий к документации XML cref правила:

  • Заключите список параметров универсального типа фигурными скобками {} вместо угловых скобок kotlin-generics <>. Это избавляет вас от необходимости c#.net экранировать последние как reference < и > - помните, что комментарии generic к документации представляют c#.net собой XML!

  • Если вы включите префикс (например, T: для типов, M: для csharp методов, P: для свойств, F: для csharp полей), компилятор не будет c-sharp выполните любую проверку visual-c# ссылки, но просто скопируйте generics значение атрибута cref прямо c# в XML-вывод документации. По xml-documentation этой причине вам придется xml-documentation использовать специальный xmldoc "ID string" syntax, который применяется в таких java-generics файлах: всегда используйте c-sharp полностью определенные идентификаторы csharp и используйте обратные кавычки kotlin-generics для ссылки на параметры универсального generic типа (`n для типов, ``n для методов).

  • Если вы опустите префикс, применяются references правила именования на обычном java-generics языке: вы можете удалить php-references пространства имен, для которых c-sharp есть инструкция using, и можете generics использовать ключевые слова xml-documentation типа языка, такие как int вместо java-generics System.Int32. Также компилятор проверит c-sharp ссылку на правильность.

Комментарий к документации XML cref шпаргалка:

namespace X
{
    using System;

    ///   (or  from outside X)
    /// 
    interface I1
    {
        ///   (or  from inside I1)
        /// 
        void M1(int p);

        /// 
        /// 
        void M2(U p);

        /// 
        /// 
        void M3(Action p);
    }

    /// 
    /// 
    interface I2
    {
        /// 
        /// 
        void M1(int p);

        /// 
        /// 
        void M2(T p);

        /// 
        /// 
        void M3(U p);
    }
}

c#

generics

reference

xml-documentation

2022-10-18T16:40:01+00:00
Вопросы с похожей тематикой, как у вопроса:

Как ссылаться на общие классы и методы в xml-документации