Как ссылаться на общие классы и методы в документации XML - PullRequest
185 голосов
/ 10 февраля 2009

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

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

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

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

Ответы [ 7 ]

243 голосов
/ 10 февраля 2009

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

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.
42 голосов
/ 10 февраля 2009
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

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

19 голосов
/ 10 декабря 2015

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

Если бы метод в 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>
17 голосов
/ 18 декабря 2016

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 refence для статического System.String.Concat(IEnumerable<string>) метода ). :

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

  • Обведите список параметров универсального типа фигурными скобками {} вместо <> угловых скобок. Это избавит вас от побега из последних как &lt; и &gt; & mdash; помните, комментарии к документации в формате 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);
    }
}
9 голосов
/ 26 октября 2011

Далее из ответов Лассе и Т.Б.К:

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

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

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

3 голосов
/ 10 ноября 2016
/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>
1 голос
/ 28 января 2012
/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.
...