2009-02-10 7 views
163

Wenn Sie XML-Dokumentation schreiben können Sie <see cref="something">something</see> verwenden, was natürlich funktioniert. Aber wie verweisen Sie auf eine Klasse oder eine Methode mit generischen Typen?Wie Verweis auf generische Klassen und Methoden in XML-Dokumentation

Wenn ich irgendwo XML-Dokumentation schreiben würde, wie würde ich die ausgefallene Klasse referenzieren? Wie kann ich eine FancyClass<string> referenzieren? Was ist mit der Methode?

Zum Beispiel in einer anderen Klasse wollte ich den Benutzer wissen lassen, dass ich eine Instanz FancyClass<int> zurückgeben werde. Wie könnte ich dafür ein Cref-Ding machen?

+0

(Blättern Sie auf meine Antwort unten auf diese 7jährigen Frage.) – JohnL4

Antwort

220

die Methode zu verweisen:

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

Danke für diese Antwort! Es fehlt tatsächlich auf der MSDN-Seite unter : http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx – joce

+5

Ich glaube tatsächlich, damit es auch in VS2010 Tooltips funktioniert, müssen Sie die Anzahl der generischen Argumente angeben, z.B "FancyClass'1 {T} .FancyMethod'1 {K} (T)" –

+0

Nicht sicher, was Sie damit meinen. Ich musste diese nie hinzufügen, und es hat immer für mich funktioniert. Haben Sie ein konkretes Beispiel, wo es nicht funktioniert? Wenn ja, bitte posten Sie es irgendwo (oder geben Sie selbst eine Antwort.) –

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

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

+2

was ist mit einer spesific Instanz von T? wie eine Schnur? Vielleicht nicht möglich? – Svish

+0

was meinst du? Sie können keine bestimmte Version deklarieren, Sie können also auch nicht darauf verweisen. –

+0

Wenn eine Methode zum Beispiel nur die Liste zurückgibt. Aber nicht wichtig :) – Svish

9

Weiteres aus den Antworten von Lasse und TBC:

/// <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 bereitstellen, während ihre Version es mit den geschweiften Klammern rendert.

+1

Die Verwendung von ** ** verursacht eine Build-Time-Warnung: ** XML-Kommentar zu 'Blah' hat das syntaktisch falsche Cref-Attribut 'System.Collections .Generic.List'1 ** - möchten Sie näher darauf eingehen, wie Sie das verwenden sollten? –

+2

Hallo Jakub, das scheint tatsächlich nicht zu funktionieren. Der einzige Weg, wie ich Tooltips auch richtig arbeiten lassen kann, ist ' 1 {T} "/>. –

+0

danke, alles funktioniert jetzt korrekt. Sowohl T: als auch die explizite (und korrekte!) Anzahl generischer Parameter werden benötigt, um ohne Warnungen zu kompilieren und korrekte Intellisense-Tooltips zu haben. Bitte aktualisieren Sie Ihre Antwort, ich werde mich freuen, sie zu aktualisieren, da es die vollständigste von allen ist. BTW, ich habe noch zu sehen, wie dies aussieht, nachdem die Dokumentation in HTML/was auch immer kompiliert wird. –

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

Keine der bisher gezeigten Antworten funktioniert komplett für mich. ReSharper konvertiert das see-Tag nicht in einen mit Strg + klickbaren Link (z. B. image here), wenn es nicht vollständig aufgelöst wird.

Wenn das Verfahren im OP in einem Namespace Test genannt wurde, die vollständig gelöst Link auf die Methode würde gezeigt werden:

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

Wie Sie in der Lage sein können, zu erarbeiten, da nur sein sollte ein Backtick vor der Anzahl der Klassentyp-Parameter, dann zwei Backticks vor der Anzahl der Methodentyp-Parameter, dann sind die Parameter der 0-indexierte Parameter mit der entsprechenden Anzahl von Backticks.

So können wir sehen, dass FancyClass 1 Klassentyp-Parameter hat, FancyMethod hat einen Typparameter und ein Objekt des FancyClass-Parametertyps wird an die Methode übergeben.

Wie Sie deutlicher in diesem Beispiel sehen kann:

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)

Or 'Class with 2 type parameters, die eine method with 3 type parameters hat, wo die Verfahrensparameter sind ClassType1, ClassType2, MethodType1, MethodType2, MethodType3)

Als zusätzliche Anmerkung, ich fand dies nirgendwo dokumentiert und ich bin kein Genie, der Compiler hat mir das alles erzählt.Alles, was Sie tun müssen, ist ein Testprojekt erstellen, enable XML documentation, dann den Code fügen Sie einen Link wollen, erarbeiten und auf den Beginn eines XML-doc Kommentar setzen (///):

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 bauen Ihr 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> 
+2

Dies sollte mehr Upvotes bekommen, vor allem wegen des Tricks, die richtige Notation zu finden, ohne müssen gehen Sie durch Versuch und Irrtum. Kudos mein Mann – Peter

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

TL; DR:

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

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

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

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

"Wie kann ich eine Referenz FancyClass<string>?"

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

Während Sie können Referenz eine Methode, deren Unterschrift enthält FancyClass<string> (z.B. als Parameter-Typ), Sie können nicht Referenz solchen geschlossenen direkt gattungsgemäßen Art. Im zweiten Beispiel wird diese Einschränkung umgangen. (Dies ist beispielsweise auf der MSDN refence page for the static System.String.Concat(IEnumerable<string>) method zu sehen). :

XML-Dokumentation Kommentar cref Regeln:

  • Surround die Parameterliste generischer Typ mit geschweiften Klammern {} statt mit <> spitzen Klammern. Dadurch ersparen Sie sich den letzten als &lt; und &gt; — erinnern, Dokumentation Kommentare sind XML!

  • Wenn Sie enthalten ein Präfix (wie T: für Typen, M: für Methoden, P: Objekte, F: für Felder), wird der Compiler keine Validierung der Referenz ausführen, sondern einfach kopieren Sie die cref Attributwert direkt zur Dokumentation XML-Ausgabe. Aus diesem Grund müssen Sie das spezielle "ID string" syntax verwenden, das in solchen Dateien gilt: Verwenden Sie immer vollständig qualifizierte Bezeichner und verwenden Sie Rückstichwörter, um generische Typparameter zu referenzieren (`n für Typen, ``n für Methoden).

  • Wenn Sie das Präfix, regelmäßige Sprache Benennungsregeln weglassen gelten: Sie Namensräume für die Drop kann es eine using Aussage, und Sie können die Sprache des Typs Schlüsselwörter wie int statt System.Int32 verwenden. Außerdem überprüft der Compiler die Referenz auf Korrektheit.

XML-Dokumentation Kommentar cref Spickzettel:

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