Lorsque vous écrivez de la documentation xml, vous pouvez l'utiliser <see cref="something">something</see>, ce qui fonctionne bien sûr. Mais comment référencer une classe ou une méthode avec des types génériques?

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

Si j'allais écrire de la documentation xml quelque part, comment pourrais-je référencer la classe fantaisie? comment puis-je référencer un FancyClass<string>? Et la méthode?

Par exemple, dans une classe différente, je voulais faire savoir à l'utilisateur que je retournerai une instance de FancyClass<int>. Comment pourrais-je faire une chose voir cref pour ça?

Pour référencer la méthode:

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

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

BTW, il était présent dans la documentation MSDN de .Net Framework 2.0 et 3.0 , mais il a disparu dans la version 3.5

TL; DR:

"Comment pourrais-je faire référence FancyClass<T>?"

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

"Et pour ça FancyClass<T>.FancyMethod<K>(T value)?"

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

"Comment puis-je référencer un FancyClass<string>?"

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

Bien que vous puissiez référencer une méthode dont la signature inclut FancyClass<string>(par exemple en tant que type de paramètre), vous ne pouvez pas référencer directement un tel type générique fermé. Le deuxième exemple contourne cette limitation. (Cela se voit par exemple sur la page de référence MSDN pour la System.String.Concat(IEnumerable<string>)méthode statique ). :

crefRègles de commentaire de la documentation XML :

• Entourez la liste des paramètres de type générique avec des accolades{} au lieu de <>crochets. Cela vous évite d'échapper à ce dernier au fur <et à mesure >- rappelez-vous, les commentaires de documentation sont XML!

• Si vous incluez un préfixe (commeT: pour les types, les M:méthodes, les P:propriétés, les F:champs), le compilateur n'effectuera aucune validation de la référence, mais copiera simplement la crefvaleur d'attribut directement dans la sortie XML de la documentation. Pour cette raison, vous devrez utiliser la syntaxe spéciale "ID string" qui s'applique à ces fichiers: utilisez toujours des identifiants complets et utilisez des astuces pour référencer les paramètres de type génériques ( `nsur les types, ``nsur les méthodes).

• Si vous omettez le préfixe , les règles de dénomination des langues normales s'appliquent: vous pouvez supprimer les espaces de noms pour lesquels il existe une usinginstruction et vous pouvez utiliser les mots-clés de type de la langue tels que intau lieu de System.Int32. En outre, le compilateur vérifiera l'exactitude de la référence.

Aide-mémoire sur les commentaires de la documentation 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);
    }
}

Aucune des réponses présentées jusqu'à présent ne fonctionne complètement pour moi. ReSharper ne convertira pas la balise see en un Ctrllien + cliquable (par exemple ) à moins qu'elle ne soit complètement résolue.

Si la méthode dans l'OP était dans un espace de noms appelé Test, le lien complètement résolu vers la méthode affichée serait:

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

Comme vous pouvez le faire, il ne devrait y avoir qu'un seul backtick avant le nombre de paramètres de type classe, puis deux backticks avant le nombre de paramètres de type de méthode, puis les paramètres sont le paramètre indexé zéro avec le nombre approprié de backticks.

Nous pouvons donc voir qu'il FancyClassa un paramètre de type de classe, FancyMethodun paramètre de type et qu'un objet du FancyClasstype de paramètre sera transmis à la méthode.

Comme vous pouvez le voir plus clairement dans cet exemple:

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

Le lien devient:

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

Ou « classe avec deux paramètres de type qui a une méthode avec trois paramètres de type où les paramètres de la méthode sont ClassType1, ClassType2, MethodType1, MethodType2, MethodType3»

En plus, je n'ai trouvé cela documenté nulle part et je ne suis pas un génie, le compilateur m'a dit tout cela. Tout ce que vous avez à faire est de créer un projet de test, d' activer la documentation XML , puis d'insérer le code pour lequel vous souhaitez établir un lien et de mettre le début d'un commentaire de doc XML dessus ( ///):

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

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

Générez ensuite votre projet et la documentation XML générée inclut le lien dans l' élément doc-> members-> membersous l'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>

Plus loin des réponses de Lasse et TBC:

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

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

fournira également des info-bulles correctement, tandis que leur version le rend avec les accolades.

/// 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.