Générer automatiquement la documentation des fonctions dans Visual Studio

89

Je me demandais s'il existe un moyen (espérons-le, un raccourci clavier) de créer des en-têtes de fonction de génération automatique dans Visual Studio.

Exemple:

Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)

Et cela deviendrait automatiquement quelque chose comme ça ...


'---------------------------------- 
'Pre: 
'Post:
'Author: 
'Date: 
'Param1 (String): 
'Param2 (Integer): 
'Summary: 
Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)
Ryan M
la source
1
Si vous avez atterri sur cette page parce que cette fonctionnalité semble être interrompue dans votre IDE, vous devez vous assurer que votre code se compile et réessayer. Cette fonctionnalité ne fonctionne pas lorsque votre code comporte des erreurs d'analyse.
krowe2
Comment générer une liste de tâches dans xamarin?
Manthan

Réponses:

158

Faites que "trois marqueurs de commentaire simples"

En C # c'est ///

qui crache par défaut:

/// <summary>
/// 
/// </summary>
/// <returns></returns>

Voici quelques conseils sur la modification des modèles VS.

Michael Paulukonis
la source
7
Et dans VB.NET, il s'agit de guillemets simples triples (comme mentionné dans une autre réponse)
peSHIr
1
C'est plutôt chouette, je ne savais pas à ce sujet
Brendan
"Générer des commentaires de documentation XML pour ///" ne fonctionnera pas si la ligne d'espacement non blanche précédente commence par "///"
Moon Waxing
Est-il possible de le faire automatiquement sur chaque méthode, propriété et variable? Même si le code existe déjà?
Robin Bruneel
lien astuces corrigé à nouveau . maudit, web à sens unique!
Michael Paulukonis
48

GhostDoc !

Faites un clic droit sur la fonction, sélectionnez "Documenter ceci" et

private bool FindTheFoo(int numberOfFoos)

devient

/// <summary>
/// Finds the foo.
/// </summary>
/// <param name="numberOfFoos">The number of foos.</param>
/// <returns></returns>
private bool FindTheFoo(int numberOfFoos)

(oui, tout est généré automatiquement).

Il prend en charge C #, VB.NET et C / C ++. Il est par défaut mappé sur Ctrl+ Shift+ D.

N'oubliez pas: vous devez ajouter des informations au-delà de la signature de la méthode dans la documentation. Ne vous contentez pas de la documentation générée automatiquement. La valeur d'un outil comme celui-ci est qu'il génère automatiquement la documentation qui peut être extraite de la signature de la méthode, donc toute information que vous ajoutez doit être de nouvelles informations.

Cela étant dit, je préfère personnellement lorsque les méthodes sont totalement auto-documentées, mais parfois vous aurez des normes de codage qui imposent une documentation extérieure, puis un outil comme celui-ci vous fera économiser beaucoup de frappe.

Rasmus Faber
la source
16
Et c'est exactement le genre de «documentation» que je déteste. Il ajoute simplement des octets sans rien me dire, les noms de méthode et de paramètre ne me le disent pas déjà. Ne faites pas cela, sans modifier le commentaire en quelque
chose qui
12
Bien sûr, vous devriez le modifier pour ajouter des informations. Mais en tant que modèle, c'est très agréable.
Rasmus Faber
3
@Rasmus: C'est un modèle qui, pour une bonne documentation, devrait être complètement jeté et réécrit de toute façon, car il n'a pas de contenu informatif. Donc, c'est en fait plus d'effort que s'il était juste vide.
Joey
35
///

est le raccourci pour obtenir le bloc de commentaires Description de la méthode. Mais assurez-vous d'avoir écrit le nom et la signature de la fonction avant de l'ajouter. Écrivez d'abord le nom et la signature de la fonction.

Ensuite, au-dessus du nom de la fonction, tapez simplement ///

et vous l'obtiendrez automatiquement

entrez la description de l'image ici

Bimzee
la source
4
belle caractéristique inhabituelle d'un post, votre animation.
n611x007
1
Comment as-tu fais ça? J'aime cette réponse. Jamais vu cela auparavant.
Matthis Kohli
2
c'est bien. un ajout serait des paramètres de la fonction.
amit jha
19

Visual Assist a également une bonne solution et est très personnalisable.

Après l'avoir peaufiné pour générer des commentaires de style doxygène, ces deux clics produiraient -

/**
* Method:    FindTheFoo
* FullName:  FindTheFoo
* Access:    private 
* Qualifier:
* @param    int numberOfFoos
* @return   bool
*/
private bool FindTheFoo(int numberOfFoos)
{

}

(Sous les paramètres par défaut, c'est un peu différent.)


Modifier: La façon de personnaliser le texte de la `` méthode de document '' est sous VassistX-> Options d'assistance visuelle-> Suggestions, sélectionnez `` Modifier les extraits VA '', Langue: C ++, Type: Refactoring, puis allez dans `` Méthode de document '' et personnalisez. L'exemple ci-dessus est généré par:

va_doxy

Ofek Shilon
la source
Veuillez partager comment vous avez configuré cela en VA
Damian
Élaboré à la réponse. J'espère que cela t'aides.
Ofek Shilon
Pour insérer l'extrait de code: avec le curseur dans le nom / la signature de la méthode, alt + shift + q> "méthode de document"
Andrew
13

Normalement, Visual Studio le crée automatiquement si vous ajoutez trois marqueurs de commentaire uniques au-dessus de l'élément que vous souhaitez commenter (méthode, classe).

En C #, ce serait /// .

Si Visual Studio ne le fait pas, vous pouvez l'activer dans

Options-> Éditeur de texte-> C # -> Avancé

et vérifie

Générer des commentaires de documentation XML pour ///

description illustrée

Domysee
la source
3

Dans Visual Basic, si vous créez d'abord votre fonction / sous-marin, puis sur la ligne au-dessus, vous tapez «trois fois, il générera automatiquement le xml pertinent pour la documentation. Cela apparaît également lorsque vous passez la souris dans intellisense et lorsque vous utilisez la fonction.

Paul Ishak
la source
2

Vous pouvez utiliser des extraits de code pour insérer les lignes de votre choix.

De plus, si vous tapez trois guillemets simples ('' ') sur la ligne au-dessus de l'en-tête de la fonction, il insérera le modèle d'en-tête XML que vous pourrez ensuite remplir.

Ces commentaires XML peuvent être interprétés par le logiciel de documentation et ils sont inclus dans la sortie de construction sous forme de fichier assembly.xml. Si vous conservez ce fichier XML avec la DLL et faites référence à cette DLL dans un autre projet, ces commentaires deviennent disponibles dans intellisense.

DCNYAM
la source
C'est VB.NET: en C # c'est ///
peSHIr
0

Je travaille sur un projet open-source appelé Todoc qui analyse les mots pour produire automatiquement une sortie de documentation appropriée lors de l'enregistrement d'un fichier. Il respecte les commentaires existants et est vraiment rapide et fluide.

http://todoc.codeplex.com/

Mathias Lykkegaard Lorenzen
la source