Beim Schreiben von XML-Dokumentation können Sie verwenden <see cref="something">something</see>, was natürlich funktioniert. Aber wie referenzieren Sie eine Klasse oder eine Methode mit generischen Typen?

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

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

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

So verweisen Sie auf die Methode:

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

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

Übrigens war es in der MSDN-Dokumentation von .Net Framework 2.0 und 3.0 vorhanden , aber es verschwand in der Version 3.5

TL; DR:

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

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

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

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

"Wie kann ich auf a verweisen FancyClass<string>?"

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

Während Sie auf eine Methode verweisen können , deren Signatur enthält FancyClass<string>(z. B. als Parametertyp), können Sie einen solchen geschlossenen generischen Typ nicht direkt referenzieren. Das zweite Beispiel umgeht diese Einschränkung. (Dies ist z. B. auf der MSDN-Referenzseite für die statische System.String.Concat(IEnumerable<string>)Methode zu sehen. ) ::

Kommentarregeln für XML-Dokumentation cref:

• Umgeben Sie die generische Typparameterliste mit geschweiften Klammern {} anstatt mit <>spitzen Klammern. Dies erspart Ihnen die Flucht vor letzterem, da - <und >denken Sie daran, dass Dokumentationskommentare XML sind!

• Wenn Sie ein Präfix einfügen (z. B.T: für Typen, M:Methoden, P:Eigenschaften,F: Felder), führt der Compiler keine Validierung der Referenz durch, sondern kopiert einfach den crefAttributwert direkt in die XML-Dokumentationsausgabe. Aus diesem Grund müssen Sie die spezielle "ID-Zeichenfolge" -Syntax verwenden , die in solchen Dateien gilt: Verwenden Sie immer vollqualifizierte Bezeichner und Backticks, um auf generische Typparameter zu verweisen ( `nauf Typen, ``nauf Methoden).

• Wenn Sie das Präfix weglassen , gelten reguläre Sprache Benennungsregeln: Sie Namensräume für die Drop kann es eine ist usingAussage, und Sie können die Sprache der Art als solche Schlüsselwörter verwenden , intstatt System.Int32. Außerdem überprüft der Compiler die Referenz auf Richtigkeit.

Kommentar- crefSpickzettel zur XML-Dokumentation :

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

Keine der bisher gezeigten Antworten funktioniert vollständig für mich. ReSharper konvertiert das see-Tag nicht in einen Ctrl+ klickbaren Link (z ), es sei denn, es wird vollständig aufgelöst.

Wenn sich die Methode im OP in einem aufgerufenen Namespace befindet Test, lautet der vollständig aufgelöste Link zu der gezeigten Methode:

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

Wie Sie vielleicht herausfinden können, sollte es nur einen Backtick vor der Anzahl der Klassentypparameter geben, dann zwei Backticks vor der Anzahl der Methodentypparameter, dann sind die Parameter der nullindizierte Parameter mit der entsprechenden Anzahl von Backticks.

Wir können also sehen, dass FancyClasses einen Klassentypparameter, FancyMethodeinen Typparameter und ein Objekt von gibtFancyClass Parametertyps an die Methode übergeben werden.

Wie Sie in diesem Beispiel deutlicher sehen können:

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 „Klasse mit zwei Typparametern , die ein Verfahren mit drei Typparametern aufweisen , wo die Verfahrensparameter sind ClassType1, ClassType2, MethodType1, MethodType2, MethodType3“

Als zusätzliche Anmerkung fand ich dies nirgendwo dokumentiert und ich bin kein Genie, der Compiler hat mir das alles erzählt. Sie müssen lediglich ein Testprojekt erstellen, die XML-Dokumentation aktivieren , dann den Code einfügen, für den Sie einen Link erstellen möchten, und einen XML-Dokumentkommentar darauf 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) { }
    }
}

Erstellen Sie dann Ihr Projekt, und die ausgegebene XML-Dokumentation enthält den Link im Element doc-> members-> memberunter 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>

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

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

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