При написании XML-документации вы можете использовать <see cref="something">something</see>, что, конечно, работает. Но как вы ссылаетесь на класс или метод с универсальными типами?

public class FancyClass<T>
{
  public string FancyMethod<K>(T value) { return "something fancy"; }
}

Если бы я собирался написать где-нибудь документацию xml, как бы я сослался на причудливый класс? как я могу сослаться наFancyClass<string> ? Как насчет метода?

Например, в другом классе я хотел, чтобы пользователь знал, что я верну экземпляр FancyClass<int>. Как я могу сделать что-нибудь для этого?

Для ссылки на метод:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.

/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

Кстати, он присутствовал в документации MSDN .Net Framework 2.0 и 3.0 , но исчез в версии 3.5

TL; DR:

"Как бы я сослался FancyClass<T>?"

   /// <see cref="FancyClass{T}"/>

"Как насчет FancyClass<T>.FancyMethod<K>(T value)?"

   /// <see cref="FancyClass{T}.FancyMethod{K}(T)"/>

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

   /// <see cref="SomeType.SomeMethod(FancyClass{string})"/>
   /// <see cref="FancyClass{T}"/> whose generic type argument is <see cref="string"/>

Хотя вы можете ссылаться на метод, чья сигнатура включает FancyClass<string>(например, в качестве типа параметра), вы не можете напрямую ссылаться на такой закрытый универсальный тип. Второй пример работает вокруг этого ограничения. (Это видно, например, на странице ссылки MSDN для статического System.String.Concat(IEnumerable<string>)метода ). :

crefПравила комментирования XML-документации :

• Обведите список параметров универсального типа фигурными скобками,{} а не <>угловыми скобками. Это избавит вас от возможности избежать последнего, поскольку <и >- помните, комментарии к документации в формате XML!

• Если вы включите префикс (например,T: для типов, M:для методов, P:для свойств, F:для полей), компилятор не будет выполнять проверку ссылки, а просто скопирует crefзначение атрибута прямо в вывод XML документации. По этой причине вам придется использовать специальный синтаксис «строка идентификатора», который применяется в таких файлах: всегда использовать полностью определенные идентификаторы и использовать обратные ссылки для ссылки на параметры универсального типа ( `nдля типов, ``nдля методов).

• Если вы пропустите префикс , применяются обычные правила именования языков: вы можете отбросить пространства имен, для которых есть usingоператор, и можете использовать ключевые слова типа языка, например intвместо System.Int32. Также компилятор проверит ссылку на правильность.

Шпаргалка с комментариями к документации XML cref:

namespace X
{
    using System;

    /// <see cref="I1"/>  (or <see cref="X.I1"/> from outside X)
    /// <see cref="T:X.I1"/>
    interface I1
    {
        /// <see cref="I1.M1(int)"/>  (or <see cref="M1(int)"/> from inside I1)
        /// <see cref="M:X.I1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I1.M2{U}(U)"/>
        /// <see cref="M:X.I1.M2``1(``0)"/>
        void M2<U>(U p);

        /// <see cref="I1.M3(Action{string})"/>
        /// <see cref="M:X.I1.M3(System.Action{System.String})"/>
        void M3(Action<string> p);
    }

    /// <see cref="I2{T}"/>
    /// <see cref="T:X.I2`1"/>
    interface I2<T>
    {
        /// <see cref="I2{T}.M1(int)"/>
        /// <see cref="M:X.I2`1.M1(System.Int32)"/>
        void M1(int p);

        /// <see cref="I2{T}.M2(T)"/>
        /// <see cref="M:X.I2`1.M2(`0)"/>
        void M2(T p);

        /// <see cref="I2{T}.M3{U}(U)"/>
        /// <see cref="M:X.I2`1.M3``1(``0)"/>
        void M3<U>(U p);
    }
}

Ни один из приведенных ответов не работает для меня полностью. ReSharper не будет преобразовывать тег see в Ctrlссылку + click -able (например, ), пока он полностью не разрешится.

Если бы метод в OP находился в вызванном пространстве имен Test, полностью разрешенная ссылка на показанный метод была бы:

<see cref="M:Test.FancyClass`1.FancyMethod``1(`0)"/>

Как вы можете выяснить, перед числом параметров типа класса должен быть только один обратный трюк, затем два обратных тика перед числом параметров типа метода, тогда параметры являются индексированным параметром с нулевым индексом и соответствующим количеством обратных токов.

Таким образом, мы можем видеть, что FancyClassимеет один параметр типа класса, FancyMethodимеет один параметр типа и объектFancyClass параметра будет передан методу.

Как вы можете видеть более ясно в этом примере:

namespace Test
{
    public class FancyClass<A, B>
    {
        public void FancyMethod<C, D, E>(A a, B b, C c, D d, E e) { }
    }
}

Ссылка становится:

M:Test.FancyClass`2.FancyMethod``3(`0,`1,``0,``1,``2)

Или «Класс с параметрами два типа , который имеет метод с тремя параметрами типа , где параметры метода ClassType1, ClassType2, MethodType1, MethodType2, MethodType3»

Как дополнительное примечание, я нигде не нашел этого документированного, и я не гений, компилятор сказал мне все это. Все, что вам нужно сделать, это создать тестовый проект, включить XML-документацию , затем вставить код, для которого вы хотите разработать ссылку, и поместить в него начало XML-документа ( ///):

namespace Test
{
    public class FancyClass<T>
    {
        ///
        public string FancyMethod<K>(T value) { return "something fancy"; }
    }

    public class Test
    {
        public static void Main(string[] args) { }
    }
}

Затем создайте свой проект, и выводимая документация XML будет содержать ссылку в элементе doc-> members-> memberпод атрибутом name:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Test</name>
    </assembly>
    <members>
        <member name="M:Test.FancyClass`1.FancyMethod``1(`0)">

        </member>
    </members>
</doc>

Далее из ответов Лассе и TBC:

/// <see cref="T:FancyClass`1{T}"/> for more information.

/// <see cref="M:FancyClass`1{T}.FancyMethod`1{K}(T)"/> for more information.

также будет правильно отображать всплывающие подсказки, в то время как их версия отображает фигурные скобки.

/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>

/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.