Referenzieren von generischen Klassen und Methoden in der XML-Dokumentation

Beim schreiben von xml-Dokumentation, die Sie verwenden können <see cref="something">something</see>das funktioniert natürlich. Aber wie Sie auf eine Klasse oder eine Methode mit generischen Typen?

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

Wenn ich im Begriff war, zu schreiben, die xml-Dokumentation, die irgendwo, wie würde ich mich auf der fancy-Klasse? wie kann ich mich auf eine FancyClass<string>? Was ist die Methode?

Beispielsweise in eine andere Klasse wollte ich lassen den Benutzer wissen, dass ich wieder eine Instanz der FancyClass<int>. Wie könnte ich ein sehen cref Sache?

InformationsquelleAutor der Frage Svish | 2009-02-10

  1. 229

    Referenz der Methode:

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

    InformationsquelleAutor der Antwort Lasse Vågsæther Karlsen

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

    BTW, es war in der MSDN-Dokumentation von .Net Framework 2.0 und 3.0aber es verschwanden in der version 3.5

    InformationsquelleAutor der Antwort thinkbeforecoding

  3. 15

    Keine Antworten bisher gezeigten Arbeit, die vollständig für mich. ReSharper nicht konvertieren siehe tag in ein Strg + anklickbarer link (z.B. Referenzieren von generischen Klassen und Methoden in der XML-Dokumentation), es sei denn, es vollständig aufgelöst wird.

    Wenn die Methode in der OP wurden in einem namespace mit dem Namen Testdie völlig aufgelöst link zu der gezeigten Methode wäre:

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

    Wie Sie vielleicht in der Lage sein, zu erarbeiten, es sollte auch nur einen umgekehrten Apostroph vor die Zahl der Klasse-Typ, Parameter, dann zwei backticks, bevor die Anzahl von Methode, Typ, Parameter, dann werden die Parameter sind 0-indiziert-parameter mit der entsprechenden Anzahl von backticks.

    So können wir sehen, dass FancyClass hat 1 Klasse Typ-parameter, FancyMethod hat einen Typ-parameter, und ein Objekt der FancyClass parameter Typ wird an die Methode übergeben werden.

    Wie können Sie mehr klar sehen, in diesem Beispiel:

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

    Der link wird:

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

    Oder 'Class with 2 type parameters die eine method with 3 type parameters wo die Parameter der Methode sind ClassType1ClassType2MethodType1MethodType2MethodType3)

    Als zusätzlicher Hinweis, ich wusste nicht, dass dies irgendwo dokumentiert und ich bin nicht ein Genie, der compiler hat mir alles gesagt. Alles, was Sie tun müssen ist, erstellen Sie ein test-Projekt, aktivieren der XML-Dokumentationdann fügen Sie den code, den Sie möchten, um herauszufinden, einen link, und setzen Sie den start in ein XML-Dokument kommentieren (///):

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

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

    Dann erstellen Sie das Projekt, und die ausgegebenen XML-Dokumentation enthält den link in der doc->members->member element unter dem Attribut name:

    <?xml version="1.0"?>
<doc>
    <assembly>
        <name>Test</name>
    </assembly>
    <members>
        <member name="M:Test.FancyClass`1.FancyMethod``1(`0)">

        </member>
    </members>
</doc>

    InformationsquelleAutor der Antwort MrLore

  4. 11

    TL;DR:

    "Wie würde ich mich auf FancyClass<T>?"

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

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

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

    "Wie kann ich mich auf eine FancyClass<string>?"

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

    Während Sie kann Referenz an eine Methode, deren Signatur enthält FancyClass<string> (z.B. als parameter-Typ), Sie nicht Referenz wie einen geschlossenen generischen Typ direkt. Das zweite Beispiel arbeitet rund um diese Einschränkung. (Dies zeigt sich z.B. an der MSDN-Referenzmodell Seite für die statische System.String.Concat(IEnumerable<string>) Methode). :

    XML-Dokumentation-Kommentar cref Regeln:

    • Umgeben den generischen Typ-parameter-Liste mit geschweiften Klammern {} statt mit <> Spitzen Klammern. Dies erspart Ihnen die Flucht, die letztere als &lt; und &gt; — denken Sie daran, Dokumentation Kommentare sind XML!

    • Wenn Sie einen Präfix (wie T: für Typen M: für Methoden P: für Eigenschaften F: für die Felder), der compiler führt keine Validierung der Referenz, sondern kopieren einfach die cref Attribut-Wert direkt in die Dokumentation der XML-Ausgabe. Aus diesem Grund müssen Sie die besonderen "ID-string" syntax , gilt in solchen Dateien: verwenden Sie immer voll qualifizierten Bezeichner und verwenden backticks Referenz generischen Typ-Parameter (`n auf Typen ``n auf Methoden).

    • Wenn Sie kein Präfix angebenreguläre Sprache naming Regeln gelten: Sie können die drop-namespaces, für die es eine using - Anweisung, und Sie können die Sprache die Art keywords wie int statt System.Int32. Auch der compiler überprüfen Sie die Referenz für die Richtigkeit.

    XML-Dokumentation-Kommentar cref cheat sheet:

    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);
    }
}

    InformationsquelleAutor der Antwort stakx

  5. 9

    Weiter von den Antworten, die von Lasse und T. B. C:

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

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

    wird auch tooltips korrekt, in der Erwägung, dass Ihre version rendert es mit den geschweiften Klammern.

    InformationsquelleAutor der Antwort Stephen Drew

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

    InformationsquelleAutor der Antwort JohnL4

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

    InformationsquelleAutor der Antwort Max Toro

Schreibe einen Kommentar