Як посилатися на загальні класи та методи в документації 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.