web-dev-qa-db-fra.com

Comment référencer des classes et des méthodes génériques dans la documentation XML

Lors de la rédaction de la documentation XML, vous pouvez utiliser <see cref="something">something</see>, qui fonctionne bien sûr. Mais comment référencez-vous 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 je devais écrire la documentation XML quelque part, comment pourrais-je référencer la classe de fantaisie? comment puis-je référencer un FancyClass<string>? Qu'en est-il de la méthode?

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

c#genericsreferencexml-documentation
186
Svish

Pour référencer la méthode:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.
244
Lasse Vågsæther Karlsen
/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

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

43
thinkbeforecoding

Aucune des réponses montrées jusqu'ici ne fonctionne complètement pour moi. ReSharper ne convertira pas la balise see en un Ctrl+ lien cliquable (par exemple image here ) à moins que cela ne résolve complètement.

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

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

Comme vous pourrez peut-être vous en sortir, il ne devrait y avoir qu’un backtick avant le nombre de paramètres de type classe, puis deux backticks avant le nombre de paramètres de type méthode, les paramètres étant alors le paramètre à index zéro avec le nombre approprié de backticks.

Nous pouvons donc voir que FancyClass a un paramètre de type de classe, FancyMethod a un paramètre de type et qu'un objet du type de paramètre FancyClass 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 méthode sont ClassType1, ClassType2, MethodType1, MethodType2, MethodType3 "

En guise de remarque supplémentaire, 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, activer la documentation XML , puis d'insérer le code pour lequel vous souhaitez créer un lien et de placer le début d'un commentaire de document XML (///):

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 fournie inclut le lien dans l'élément doc-> members-> member sous 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>
19
MrLore

TL; DR:

"Comment ferais-je référence à FancyClass<T>?"

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

"Qu'en est-il de FancyClass<T>.FancyMethod<K>(T value)?"

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

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

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

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

Commentaire de la documentation XML cref règles:

  • Entourez la liste des paramètres de type générique avec des accolades {} au lieu de crochets <>. Cela vous évite d'échapper à ces derniers sous les noms &lt; Et &gt; - rappelez-vous, les commentaires de la documentation sont au format XML!

  • Si vous incluez un préfixe (tel que T: pour les types, M: Pour les méthodes, P: pour les propriétés, F: pour les champs), le compilateur n'effectuera aucune validation de la référence mais copiera simplement la valeur de l'attribut cref directement dans la sortie XML de la documentation. Pour cette raison, vous devrez utiliser la syntaxe spéciale "ID string" qui s'applique à ce type de fichier: utilisez toujours des identificateurs complets, et des backticks pour référencer les paramètres de type générique (`n sur les types, ``n sur les méthodes).

  • Si vous omettez le préfixe , les règles de nommage linguistique habituelles s'appliquent: vous pouvez supprimer les espaces de noms pour lesquels il existe une instruction using, et vous pouvez utiliser les mots-clés de type de la langue tels que int au lieu de System.Int32. En outre, le compilateur vérifiera l'exactitude de la référence.

Commentaire de la documentation XML cref Aide-mémoire:

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

Plus loin des réponses de Lasse et 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.

fournira également les info-bulles correctement, alors que leur version le rendra avec les accolades.

10
Stephen Drew
/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>.
/// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>
4
JohnL4
/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.
1
Max Toro