Génération automatique de la documentation sur les fonctions dans Visual Studio
Je me demandais s'il existait un moyen (espérons-le, un raccourci clavier) de créer des en-têtes 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)
Faire que "trois simples marqueurs de commentaires"
En C # c'est ///
qui par défaut crache:
/// <summary>
///
/// </summary>
/// <returns></returns>
Voici quelques conseils sur la modification de modèles de VS.
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 supporte C #, VB.NET et C/C++. Il est mappé par défaut sur Ctrl+Shift+D.
Rappelez-vous: vous devez ajouter des informations au-delà de la signature de la méthode à la documentation. Ne vous arrêtez pas à la documentation générée automatiquement. La valeur d'un outil comme celui-ci est qu'il génère automatiquement la documentation pouvant être extraite de la signature de la méthode. Par conséquent, toute information ajoutée doit être nouvelle information .
Cela étant dit, je préfère personnellement lorsque les méthodes sont totalement auto-documentées, mais vous aurez parfois des normes de codage qui imposeront une documentation externe, puis un outil comme celui-ci vous évitera beaucoup de dactylographie.
///
est le raccourci pour obtenir le bloc de commentaires Method Description. Mais assurez-vous d’avoir écrit le nom de la fonction et sa signature avant de l’ajouter. Commencez par écrire le nom de la fonction et sa signature.
Ensuite, au-dessus du nom de la fonction, tapez simplement ///
et vous l'obtiendrez automatiquement
Visual Assist a un solution de Nice aussi, et est hautement costumizable.
Après l'avoir modifié pour générer des commentaires de style doxygen, 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.)
Éditer: La manière de personnaliser le texte de la "méthode du document" est sous VassistX-> Options d’assistance visuelle-> Suggestions, sélectionnez "Éditer VA Extraits de code", Langue: C++, Type: Refactoring, puis 'Méthode du document' et personnalisation. L'exemple ci-dessus est généré par:
Normalement, Visual Studio le crée automatiquement si vous ajoutez trois marqueurs de commentaire uniques au-dessus de ce que vous souhaitez commenter (méthode, classe).
En C #, ce serait /// _ .
Si Visual Studio ne le fait pas, vous pouvez l'activer dans
Options-> Editeur de texte-> C # -> Avancé
et vérifie
Générer des commentaires de la documentation XML pour ///
Dans Visual Basic, si vous créez d’abord votre fonction/votre sous-objet, vous tapez trois fois 'sur la ligne située au-dessus de celui-ci. Il générera automatiquement le xml correspondant à des fins de documentation. Cela apparaît également lorsque vous passez la souris dans IntelliSense et lorsque vous utilisez la fonction.
Vous pouvez utiliser des extraits de code pour insérer les lignes de votre choix.
De même, si vous tapez trois guillemets simples ('' ') sur la ligne située au-dessus de l'en-tête de la fonction, le modèle d'en-tête XML sera inséré et pourra être rempli.
Ces commentaires XML peuvent être interprétés par le logiciel de documentation et sont inclus dans la sortie de la construction en tant que fichier Assembly.xml. Si vous conservez ce fichier XML avec le DLL et référencez-le DLL dans un autre projet, ces commentaires deviennent disponibles dans intellisense.
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 très rapide et fluide.