Як посилатися на загальні класи та методи в документації xml


198

При написанні XML документації ви можете використовувати <see cref="something">something</see>, що працює, звичайно. Але як ви посилаєтесь на клас чи метод із загальними типами?

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

Якщо я збирався десь написати документацію xml, як би я посилався на клас фантазії? як я можу посилатись на a FancyClass<string>? Що з методом?

Наприклад, в іншому класі я хотів повідомити користувачеві про те, що я поверну йому екземпляр FancyClass<int>. Як я міг зробити для цього бачення крефів?

Відповіді:


257

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

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

3
Дякую за цю відповідь! Це на самому справі відсутній сторінці MSDN по <см>: msdn.microsoft.com/en-us/library/acd0tfbe.aspx
— Joce

6
Я фактично вважаю, що він також працює в підказках VS2010, вам потрібно вказати кількість загальних аргументів, наприклад, "FancyClass 1{T}.FancyMethod1 {K} (T)"
— Стівен Дрю

Не впевнений, що ви про це маєте на увазі. Мені ніколи не доводилося додавати їх, і це завжди працювало на мене. Чи є у вас конкретний приклад, коли це не працює? Якщо так, будь ласка, опублікуйте його десь (або навіть надайте відповідь самостійно.)
— Lasse V. Karlsen

@Lasse, див. Відповідь та коментарі Стіва нижче. Ваша відповідь не стосується правильних підказок Intellisense.
— Якуб Янушкевич

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

До речі, він був присутній у документації MSDN .Net Framework 2.0 та 3.0 , але він не був доступний у версії 3.5


4
як щодо специфічного екземпляра T? як рядок? Можливо, це не можливо?
— Свиш

Що ви маєте на увазі? Ви не можете оголосити конкретну версію, тому ви також не можете посилатися на неї.
— Лассе В. Карлсен

Якщо метод, наприклад, повертає лише Список <string>, наприклад. Але не важливо :)
— Свиш

7
Так, мені було цікаво також ... resharpers хихикає під час написання FancyClass {string}, але не під час написання FancyClass {String} ...
— thinkbeforecoding

6
Причиною вищезазначеного спостереження "Подумайте перед кодуванням" є те, що воно не працює з псевдонімами c #. Наприклад, вам потрібно використовувати Int32замість int, Singleа не floatінше (розміщуючи цю інформацію тут, якщо хтось інший натикається на це)
— AnorZaken

27

TL; DR:

"Як я б посилався FancyClass<T>?"

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

"Про що FancyClass<T>.FancyMethod<K>(T value)?"

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

"Як я можу посилатись на a 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 :

  • Обведіть список параметрів узагальненого типу фігурними дужками,{} а не <>кутовими дужками. Це позбавить вас від уникнення останнього, як &lt;і &gt;- пам’ятайте, коментарі до документації - це 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);
    }
}

Як посилатися лише на Tчастину?
— nawfal

4
<typeparamref name="T"/>
— З'ясував

21

Жодна із наведених відповідей поки що не працює для мене повністю. ReSharper не перетворить тег see у Ctrl+ посилання, що може натискати (наприклад зображення тут), якщо він повністю не вирішиться.

Якби метод в ОП був у виклику простору імен 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>

3
Це повинно отримати більше результатів, особливо через хитрість знайти правильну нотацію, не проходячи пробну помилку. Кудо мій чоловік
— Пітер

10

Далі від відповідей Лассе та TBC:

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

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

також надасть підказки правильно, тоді як їх версія надає це фігурними дужками.


2
Використовуючи <див. Cref = "System.Collections.Generic.List 1{T}"/>** causes a build-time warning: **XML comment on 'Blah' has syntactically incorrect cref attribute 'System.Collections.Generic.List1 <T> - ви б хотіли детальніше розібратися, як слід це використовувати?
— Якуб Янушкевич

2
Привіт Якуб, це, здається, не працює. Єдиний спосіб, коли я можу також отримати підказки для правильної роботи, - це <see cref = "T: <fullTypeName>` 1 {T} "/>.
— Стівен Дрю

2
Добре, я частково це зрозумів. Якщо сам метод не є загальним (наприклад, у списку <T> .Add ()), це працює: <див. Cref = "M: System.Collections.Generic.List`1 {T} .Add (T)" /> .
— Якуб Янушкевич

1
Здається, це не працює для мене. Я <see cref = "M: System.Collections.Generic.List`1 {T}" /> у заголовку коментаря для загального методу розширення, який я написав (перетворює ArrayList у список <T>), але ReSharper позначає це як помилка синтаксису, і IntelliSense просто відображає це дослівно. VS 2010 / R № 6.1.37.86
— Майк Лукс

8
Ага! Мені вдалося змусити <див. Cref = "T: System.Collections.Generic.List`1" /> " працювати. Отже, використовуючи T: замість фігурних дужок зробили трюк. Це розширює повний простір імен, і трюк не працює, якщо ви не включите простір імен, тож він не ідеальний, але це буде.
— Майк Лукс

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

3
Зауважте, що інші відповіді стосуються того, як посилатися на загальний клас, ця відповідь показує вам, як самостійно посилатися на параметр типу, який, як було, я шукав.
— jrh

Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.