2009-02-10 15 views
163

Podczas pisania dokumentacji xml można użyć <see cref="something">something</see>, co działa oczywiście. Ale w jaki sposób odwołujesz się do klasy lub metody o typach ogólnych?Jak odnieść ogólne klasy i metody w dokumentacji xml

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

Gdybym miał gdzieś napisać dokumentację xml, jak mógłbym odwołać się do tej fantazyjnej klasy? jak mogę odwołać się do FancyClass<string>? A co z metodą?

Na przykład w innej klasie chciałem poinformować użytkownika, że ​​zwrócę instancję FancyClass<int>. Jak mógłbym to zrobić, widząc cref?

+0

(Przewiń w dół na moją odpowiedź na to pytanie 7-letniej). – JohnL4

Odpowiedz

220

Aby odnieść się do sposobu:

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

Dzięki za odpowiedź! W rzeczywistości nie ma go na stronie MSDN pod adresem : http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx – joce

+5

Naprawdę wierzę, że działa również w etykietkach narzędzi VS2010, które trzeba wskazać liczbę ogólnych argumentów, na przykład "FancyClass'1 {T} .FancyMethod'1 {K} (T)" –

+0

Nie jesteś pewien co masz na myśli. Nigdy nie musiałem ich dodawać i zawsze działało dla mnie. Czy masz konkretny przykład, w którym to nie działa? Jeśli tak, opublikuj go gdzieś (lub nawet ułóż odpowiedź samodzielnie). –

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

okazji, jest on obecny w dokumentacji MSDN .Net Framework 2.0 i 3.0, ale zniknęły w version 3.5

+2

co o Spesific instancji T? jak ciąg? Może nie jest możliwe? – Svish

+0

co masz na myśli? Nie możesz zadeklarować konkretnej wersji, więc nie możesz się do niej odwołać. –

+0

Jeśli na przykład metoda zwraca tylko listę . Ale nie ważne :) – Svish

9

dalej od odpowiedzi Lasse i TBC:

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

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

będzie również poprawnie wyświetlać podpowiedzi, podczas gdy ich wersja będzie renderować za pomocą nawiasów klamrowych.

+1

Używanie ** ** powoduje wyświetlenie ostrzeżenia o czasie działania: ** Komentarz XML do "Blah" ma składniowy niepoprawny atrybut cref "System.Collections .Generic.List'1 ** - czy chciałbyś wyjaśnić, jak należy tego użyć? –

+2

Cześć Jakub, to naprawdę nie działa. Jedynym sposobem, w jaki mogę uzyskać poprawne działanie tooltipów, jest . –

+0

dziękuję, wszystko działa poprawnie teraz. Zarówno T: jak i jawna (i poprawna!) Liczba ogólnych parametrów jest potrzebna do kompilacji bez ostrzeżeń i do posiadania prawidłowych podpowiedzi IntelliSense. Proszę zaktualizować odpowiedź, z przyjemnością ją przegłosuję, ponieważ jest to najbardziej kompletny ze wszystkich. BTW, muszę jeszcze zobaczyć, jak to wygląda po skompilowaniu dokumentacji do HTML/cokolwiek. –

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

żadna z odpowiedzi przedstawionych do tej pory całkowicie pracy dla mnie. ReSharper nie przekonwertuje tagu see na link Ctrl + klikalny (np. image here), chyba że zostanie całkowicie rozwiązany.

Jeśli metoda w PO były w przestrzeni nazw Test, całkowicie rozwiązany link do sposobu przedstawionego byłoby:

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

Jak być może uda się wypracować, nie powinno być jedynie jedno cofnięcie przed liczbą parametrów typu klasy, a następnie dwa odrzucenia przed liczbą parametrów typu metody, następnie parametry są parametrem zindeksowanym 0 z odpowiednią liczbą odrzutów.

Widzimy więc, że FancyClass ma 1 typ klasy, parametr FancyMethod ma jeden parametr, a obiekt typu FancyClass zostanie przekazany do metody.

Jak można bardziej wyraźnie zobaczyć w poniższym przykładzie:

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

Link staje:

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

Albo "Class with 2 type parameters który ma method with 3 type parameters gdzie parametry metody ClassType1, ClassType2, MethodType1, MethodType2, MethodType3)


Jako dodatkową notatkę, nie znalazłem tego udokumentowanego gdziekolwiek i nie jestem geniuszem, kompilator powiedział mi o tym wszystkim.Wszystko co musisz zrobić, to stworzyć projekt testowy, enable XML documentation, a następnie wstawić kod, który ma wypracować link i umieścić początek komentarzu XML doc na nim (///):

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

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

Następnie budować Twój projekt, a wyprowadzane dokumentacja XML zawiera link w doc -> ->membermembers elementu pod atrybutem 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

Powinno to zwiększyć liczbę upwertowań, szczególnie ze względu na lewę, aby znaleźć poprawną notację, bez konieczności przejść przez próbę i błąd, Kudos, mój człowieku – Peter

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

TL; DR:

"Jak mogę odnieść się do FancyClass<T>?"

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

"Co o FancyClass<T>.FancyMethod<K>(T value)?"

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

"Jak mogę odwołać FancyClass<string>?"

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

Podczas może odniesienia sposób których podpis zawiera FancyClass<string> (na przykład jak rodzaj parametru), użytkownik może nieodniesienia takiego typu zamkniętego rodzajowy bezpośrednio. Drugi przykład działa wokół tego ograniczenia. (Widać to np. Na MSDN refence page for the static System.String.Concat(IEnumerable<string>) method). :

XML dokumentacji komentarz cref zasady:

  • otaczają rodzajowy lista parametrów typu z klamrami {} zamiast z <> nawiasach kątowych. To oszczędza przed ucieczką od tego ostatniego jako &lt; i &gt; — pamiętaj, komentarze do dokumentacji to XML!

  • Jeśli zawierać prefiks (np T: dla typów, M: dla metod, P: dla właściwości, F: dla pól), kompilator nie będzie wykonywać żadnych walidację odniesienia, ale po prostu skopiować wartość atrybutu cref bezpośrednio do dokumentacji wyjścia XML. Z tego powodu będziesz musiał użyć specjalnego "ID string" syntax, który ma zastosowanie w takich plikach: zawsze używaj w pełni kwalifikowanych identyfikatorów i używaj odsunięć do odniesienia do ogólnych parametrów typów (`n o typach, ``n o metodach).

  • Pominięcie prefiks, regularne zasady nazewnictwa język zastosowanie: można upuścić nazw, dla których istnieje using oświadczenie, i można użyć typu słowa kluczowe języku, takich jak int zamiast System.Int32. Ponadto kompilator sprawdzi poprawność odniesienia.

XML dokumentacji komentarz cref Ściągawka:

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); 
    } 
} 
Powiązane problemy