2009-02-10 2 views
163

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

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

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

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

+0

(Прокрутите вниз для моего ответа на этот 7-летний вопрос.) – JohnL4

ответ

220

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

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

Спасибо за этот ответ! Это действительно отсутствует на странице MSDN по адресу : http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx – joce

+5

Я действительно верю, что он также будет работать с всплывающими подсказками VS2010, которые вам нужно указать количество общих аргументов, например «FancyClass'1 {T} .FancyMethod'1 {K} (T)" –

+0

Не уверен, что вы имеете в виду. Мне никогда не приходилось добавлять их, и это всегда сработало для меня. У вас есть конкретный пример, где он не работает? Если да, отправьте его где-нибудь (или даже представите ответ самостоятельно). –

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

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

+2

насчет spesific экземпляра Т? как строка? Может быть, это невозможно? – Svish

+0

Что вы имеете в виду? Вы не можете объявить конкретную версию, поэтому вы также не можете ссылаться на нее. –

+0

Если, например, метод возвращает только список . Но не важно :) – Svish

9

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

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

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

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

+1

Использование ** ** вызывает предупреждение о времени сборки: ** Комментарий XML к 'Blah' имеет синтаксически неправильный атрибут cref 'System.Collections .Generic.List'1 ** - Не могли бы вы рассказать о том, как следует использовать это? –

+2

Привет, Якуб. Это действительно не работает. Единственный способ, с помощью которого я могу заставить всплывающие подсказки работать правильно, - это . –

+0

спасибо, теперь все работает правильно. И T:, и явное (и правильное!) Количество общих параметров необходимы для компиляции без предупреждений и для правильной подсказки Intellisense. Пожалуйста, обновите свой ответ, я буду рад его продвигать, поскольку он является самым полным из всех. BTW, мне еще предстоит посмотреть, как это выглядит после того, как документация скомпилирована в HTML/что угодно. –

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

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

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

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

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

Таким образом, мы можем видеть, что FancyClass имеет 1 параметр типа класса, 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)

Или 'Class with 2 type parameters который имеет method with 3 type parameters где параметры метода ClassType1, ClassType2, MethodType1, MethodType2, MethodType3)


В качестве дополнительной заметки я не нашел это документально нигде, и я не гений, компилятор рассказал мне обо всем этом.Все, что вам нужно сделать, это создать тестовый проект, enable XML documentation, а затем вставить код, который вы хотите, чтобы выработать ссылку, и положил начало в 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> 
+2

Это должно получить больше очков, особенно из-за трюка, чтобы найти правильную нотацию, без необходимости Пройти пробную ошибку. – Peter

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

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 page for the static System.String.Concat(IEnumerable<string>) method). :

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

  • Surround общий список параметров типа с фигурными скобками {} вместо с <> угловых скобок. Это избавляет вас от избежания последних как &lt; и &gt; —, комментарии документации XML!

  • Если включить префикс (например, T: для типов, M: для методов, P: для свойств, F: для полей), то компилятор не будет выполнять никакой валидации ссылки, а просто скопировать значение в cref атрибута прямо на вывод документации XML. По этой причине вам придется использовать специальный "ID string" syntax, который применяется в таких файлах: всегда используйте полностью квалифицированные идентификаторы и используйте обратные ссылки для ссылки на параметры типового типа (`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); 
    } 
} 
Смежные вопросы