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


198

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?

Réponses:


257

Pour référencer la méthode:

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

3
Merci pour cette réponse! Il manque en fait sur la page de MSDN sur <see>: msdn.microsoft.com/en-us/library/acd0tfbe.aspx
joce

6
Je pense en fait que cela fonctionne également dans les info-bulles VS2010, vous devez indiquer le nombre d'arguments génériques, par exemple "FancyClass 1{T}.FancyMethod1 {K} (T)"
Stephen Drew

Je ne sais pas ce que tu veux dire à ce sujet. Je n'ai jamais eu à les ajouter, et cela a toujours fonctionné pour moi. Avez-vous un exemple spécifique où cela ne fonctionne pas? Si oui, veuillez l'afficher quelque part (ou même fournir une réponse vous-même.)
Lasse V. Karlsen

@Lasse, veuillez voir la réponse et les commentaires de Steve ci-dessous. Votre réponse ne couvre pas les info-bulles Intellisense correctes.
Jakub Januszkiewicz

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


4
qu'en est-il d'une instance spécifique de T? comme une chaîne? Peut-être pas possible?
Svish

Que voulez-vous dire? Vous ne pouvez pas déclarer une version spécifique, vous ne pouvez donc pas vous y référer non plus.
Lasse V. Karlsen

Si une méthode, par exemple, ne renvoie que List <string> par exemple. Mais ce n'est pas important :)
Svish

7
Oui, je me demandais aussi ... les resharpers se tortillent lors de l'écriture de FancyClass {string} mais pas lors de l'écriture de FancyClass {String} ...
thinkbeforecoding

6
La raison de l'observation ci-dessus de "Think Before Coding" est qu'elle ne fonctionne pas avec les alias c #. Par exemple, vous devez utiliser à la Int32place de int, Singleau lieu de floatetc. (Mettre cette information ici au cas où quelqu'un d'autre
tomberait dessus

27

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 &lt;et à mesure &gt;- 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);
    }
}

Comment référencer juste la Tpièce?
nawfal

4
<typeparamref name="T"/>
Compris

21

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 image ici) à 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>

3
Cela devrait obtenir plus de votes positifs, en particulier à cause de l'astuce pour trouver la notation correcte, sans avoir à passer par des essais et des erreurs. Bravo mon homme
Peter

10

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.


2
En utilisant <see cref = "System.Collections.Generic.List 1{T}"/>** causes a build-time warning: **XML comment on 'Blah' has syntactically incorrect cref attribute 'System.Collections.Generic.List1 <T> - voudriez-vous élaborer sur la façon de l'utiliser?
Jakub Januszkiewicz

2
Salut Jakub, Cela ne semble en effet pas fonctionner. La seule façon de faire fonctionner correctement les info-bulles consiste à <voir cref = "T: <fullTypeName>` 1 {T} "/>.
Stephen Drew

2
OK, je l'ai partiellement compris. Si la méthode elle-même n'est pas générique (comme dans List <T> .Add ()), cela fonctionne: <voir cref = "M: System.Collections.Generic.List`1 {T} .Add (T)" /> .
Jakub Januszkiewicz

1
Ne semble pas fonctionner pour moi. J'ai <voir cref = "M: System.Collections.Generic.List`1 {T}" /> dans l'en-tête de commentaire pour une méthode d'extension générique que j'ai écrite (convertit un ArrayList en une liste <T>) mais ReSharper le marque comme étant une erreur de syntaxe, et IntelliSense l'affiche textuellement. VS 2010 / R # 6.1.37.86
Mike Loux

8
Ah! J'ai pu faire fonctionner <see cref = "T: System.Collections.Generic.List`1" /> " . Ainsi, l'utilisation de T: au lieu des accolades a fait l'affaire. Il étend l'espace de noms complet, et l'astuce ne fonctionne pas si vous n'incluez pas l'espace de noms, donc ce n'est pas parfait, mais cela suffira.
Mike Loux

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

3
Notez que les autres réponses couvrent comment référencer une classe générique, cette réponse vous montre comment référencer le paramètre de type par lui-même, ce qui se trouvait être ce que je cherchais à faire.
2018

1
/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.