Comment avoir des commentaires dans IntelliSense pour la fonction dans Visual Studio?

139

Dans Visual Studio et C #, lors de l'utilisation d'une fonction intégrée telle que ToString (), IntelliSense affiche une boîte jaune expliquant ce qu'elle fait.

texte alternatif texte alternatif

Comment puis-je avoir cela pour les fonctions et les propriétés que j'écris?

Ali
la source

Réponses:

215

Pour générer une zone dans laquelle vous pouvez spécifier une description pour la fonction et chaque paramètre de la fonction, tapez ce qui suit sur la ligne avant votre fonction et appuyez sur Enter:

  • C #: ///

  • VB: '''

Voir Balises recommandées pour les commentaires de documentation (Guide de programmation C #) pour plus d'informations sur le contenu structuré que vous pouvez inclure dans ces commentaires.

Solmead
la source
2
Pour souligner: c'est une triple barre oblique en C ++ / C # (les commentaires normaux sont une double barre oblique). Et dans VB, ses deux guillemets simples, pas un guillemet double.
abelenky le
1
C'est en fait trois guillemets simples en vb
Joel Coehoorn
1
En fait, en VB, il s'agit de 3 guillemets simples: `` ''
hometoast
2
Comme alternative, dans un fichier VB, vous pouvez faire un clic droit sur une fonction ou une classe et cliquer sur "Insérer un commentaire". Pour C #, vous pouvez utiliser StyleCop qui vous demandera d'écrire de bons en
user1069816
GhostDoc est un excellent outil qui peut ajouter beaucoup de texte dans les commentaires pour vous. submain.com/products/ghostdoc.aspx
Karl Gjertsen
74

Ce dont vous avez besoin, ce sont des commentaires xml - en gros, ils suivent cette syntaxe (comme décrit vaguement par Solmead):

C #

///<summary>
///This is a description of my function.
///</summary>
string myFunction() {
     return "blah";
}

VB

'''<summary>
'''This is a description of my function.
'''</summary>
Function myFunction() As String
    Return "blah"
End Function
Tomas Aschan
la source
23

<c>text</c>- Le texte que vous souhaitez indiquer comme code.
La balise < c > vous permet d'indiquer que le texte d'une description doit être marqué comme code. Utilisez < code > pour indiquer plusieurs lignes comme code.

<code>content</code>- Le texte que vous souhaitez marquer comme code.
La balise < code > vous permet d'indiquer plusieurs lignes comme code. Utilisez < c > pour indiquer que le texte d'une description doit être marqué comme code.

<example>description</example>- Une description de l'exemple de code.
La balise < example > vous permet de spécifier un exemple d'utilisation d'une méthode ou d'un autre membre de la bibliothèque. Cela implique généralement l'utilisation de la balise < code >.

<exception cref="member">description</exception>- Une description de l'exception.
La balise < exception > vous permet de spécifier les exceptions qui peuvent être levées. Cette balise peut être appliquée aux définitions de méthodes, de propriétés, d'événements et d'indexeurs.

<include file='filename' path='tagpath[@name="id"]' />
La balise < include > vous permet de faire référence à des commentaires dans un autre fichier qui décrivent les types et les membres de votre code source. C'est une alternative au placement des commentaires de documentation directement dans votre fichier de code source. En plaçant la documentation dans un fichier séparé, vous pouvez appliquer le contrôle de code source à la documentation séparément du code source. Une personne peut faire extraire le fichier de code source et quelqu'un d'autre peut faire extraire le fichier de documentation. La balise < include > utilise la syntaxe XML XPath. Reportez-vous à la documentation XPath pour savoir comment personnaliser votre utilisation < include >.

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

Le bloc < listheader > est utilisé pour définir la ligne d'en-tête d'une table ou d'une liste de définitions. Lors de la définition d'un tableau, il vous suffit de fournir une entrée pour terme dans l'en-tête. Chaque élément de la liste est spécifié avec un bloc < élément >. Lors de la création d'une liste de définitions, vous devrez spécifier à la fois le terme et la description. Cependant, pour un tableau, une liste à puces ou une liste numérotée, il vous suffit de fournir une entrée pour la description. Une liste ou un tableau peut avoir autant de blocs < item > que nécessaire.

<para>content</para>
La balise < para > est à utiliser dans une balise, telle que < summary >, < remarques > ou < retours >, et vous permet d'ajouter de la structure au texte.

<param name="name">description</param>
La balise < param > doit être utilisée dans le commentaire d'une déclaration de méthode pour décrire l'un des paramètres de la méthode. Pour documenter plusieurs paramètres, utilisez plusieurs balises < param >.
Le texte de la balise < param > sera affiché dans IntelliSense, l'Explorateur d'objets et dans le rapport Web Commentaire de code.

<paramref name="name"/>
La balise < paramref > vous permet d'indiquer qu'un mot dans les commentaires de code, par exemple dans un bloc < summary > ou < remarques > fait référence à un paramètre. Le fichier XML peut être traité pour formater ce mot d'une manière distincte, par exemple avec une police en gras ou en italique.

< permission cref="member">description</permission>
La balise < permission > vous permet de documenter l'accès d'un membre. La classe PermissionSet vous permet de spécifier l'accès à un membre.

<remarks>description</remarks>
La balise < remarques > est utilisée pour ajouter des informations sur un type, en complétant les informations spécifiées par < summary >. Ces informations sont affichées dans l'Explorateur d'objets.

<returns>description</returns>
La balise < retours > doit être utilisée dans le commentaire pour une déclaration de méthode pour décrire la valeur de retour.

<see cref="member"/>
La balise < see > vous permet de spécifier un lien à partir du texte. Utilisez < seealso > pour indiquer que le texte doit être placé dans une section Voir aussi. Utilisez l'attribut cref pour créer des hyperliens internes vers des pages de documentation pour les éléments de code.

<seealso cref="member"/>
La balise < seealso > vous permet de spécifier le texte que vous voudrez peut-être voir apparaître dans une section Voir aussi. Utilisez < voir > pour spécifier un lien à partir du texte.

<summary>description</summary>
La balise < summary > doit être utilisée pour décrire un type ou un membre de type. Utilisez < remarques > pour ajouter des informations supplémentaires à une description de type. Utilisez l'attribut cref pour permettre aux outils de documentation tels que Sandcastle de créer des hyperliens internes vers des pages de documentation pour les éléments de code. Le texte de la balise < summary > est la seule source d'informations sur le type dans IntelliSense et est également affiché dans l'Explorateur d'objets.

<typeparam name="name">description</typeparam>
La balise < typeparam > doit être utilisée dans le commentaire pour un type générique ou une déclaration de méthode pour décrire un paramètre de type. Ajoutez une balise pour chaque paramètre de type du type ou de la méthode générique. Le texte de la balise < typeparam > sera affiché dans IntelliSense, le rapport Web de commentaires de code de l'Explorateur d'objets.

<typeparamref name="name"/>
Utilisez cette balise pour permettre aux utilisateurs du fichier de documentation de formater le mot d'une manière distincte, par exemple en italique.

<value>property-description</value>
La balise < value > vous permet de décrire la valeur représentée par une propriété. Notez que lorsque vous ajoutez une propriété via l'assistant de code dans l'environnement de développement Visual Studio .NET, il ajoute une balise < summary > pour la nouvelle propriété. Vous devez ensuite ajouter manuellement une balise < value > pour décrire la valeur que la propriété représente.

Max
la source
11

Faire des commentaires XML, comme ceci

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}
Michael Walts
la source
6
Pour les paramètres, ajoutez:///<param name="paramName">Tralala</param>
The Oddler
10

utilisez /// pour commencer chaque ligne du commentaire et que le commentaire contienne le xml approprié pour le lecteur de métadonnées.

///<summary>
/// this method says hello
///</summary>
public void SayHello();

Bien que personnellement, je pense que ces commentaires sont généralement erronés, sauf si vous développez des classes où le code ne peut pas être lu par ses consommateurs.

DévelopperChris
la source
2
ils sont bons pour les rappels de raccourcis, ou partout où vous avez du code de bibliothèque où peut-être le code est lisible mais il faut un peu de travail supplémentaire pour y accéder.
Joel Coehoorn
1
Je suis d'accord avec vous en théorie, mais si vous utilisez cette chose ghostdoc, alors vous augmentez le rapport bruit / signal à un point tel que le reste des commentaires est inutile.
DevelopingChris
9

Ceux-ci sont appelés commentaires XML . Ils font partie de Visual Studio depuis toujours.

Vous pouvez faciliter votre processus de documentation en utilisant GhostDoc , un complément gratuit pour Visual Studio qui génère des commentaires XML-doc pour vous. Placez simplement votre curseur sur la méthode / propriété que vous souhaitez documenter et appuyez sur Ctrl-Maj-D.

Voici un exemple tiré de l' un de mes messages .

J'espère que cela pourra aider :)

Igal Tabachnik
la source
6

Dans CSharp, si vous créez le contour de méthode / fonction avec ses Parms, alors lorsque vous ajoutez les trois barres obliques, il générera automatiquement la section récapitulative et parms.

Alors j'ai mis:

public string myMethod(string sImput1, int iInput2)
{
}

J'ai ensuite mis les trois /// avant et Visual Studio m'a donné ceci:

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}
Semperfi89
la source
6

Définissez des méthodes comme celle-ci et vous obtiendrez l'aide dont vous avez besoin.

    /// <summary>
    /// Adds two numbers and returns the result
    /// </summary>
    /// <param name="first">first number to add</param>
    /// <param name="second">second number to </param>
    /// <returns></returns>
    private int Add(int first, int second)
    {
        return first + second;
    }

Capture d'écran de l'utilisation du code

Recev Yildiz
la source
2

Toutes ces autres réponses ont du sens, mais sont incomplètes. Visual Studio traitera les commentaires XML, mais vous devez les activer. Voici comment procéder:

Intellisense utilisera les commentaires XML que vous entrez dans votre code source, mais vous devez les activer via les options de Visual Studio. Aller à Tools> Options> Text Editor. Pour Visual Basic, activez le paramètre Advanced> Generate XML documentation comments for '''. Pour C #, activez le paramètre Advanced> Generate XML documentation comments for ///. Intellisense utilisera les commentaires récapitulatifs une fois saisis. Ils seront disponibles à partir d'autres projets une fois le projet référencé compilé.

Pour créer externe la documentation, vous devez générer un fichier XML à travers le Project Settings> Build> XML documentation file:chemin que les contrôles de compilateur /docoption. Vous aurez besoin d'un outil externe qui prendra le fichier XML en entrée et générera la documentation dans votre choix de formats de sortie.

Sachez que la génération du fichier XML peut augmenter considérablement votre temps de compilation.

Suncat2000
la source
1

Le doc fantôme du complément Visual Studio tentera également de créer et de remplir les commentaires d'en-tête à partir du nom de votre fonction.

Mark Rogers
la source
0

Solmead a la bonne réponse. Pour plus d'informations, vous pouvez consulter les commentaires XML .

Ed S.
la source