Méthodes de synchronisation des commentaires d'interface et d'implémentation en C # [fermé]

98

Existe-t-il des moyens automatiques de synchroniser les commentaires entre une interface et son implémentation? Je les documente actuellement tous les deux et je ne souhaite pas les synchroniser manuellement.

METTRE À JOUR:

Considérez ce code:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Quand je crée une classe comme celle-ci:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Ici les commentaires ne sont pas affichés:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

La <inheritDoc/>balise générera parfaitement la documentation dans Sand Castle, mais elle ne fonctionne pas dans les infobulles intellisense.

Veuillez partager vos idées.

Merci.

Valentin Vasilyev
la source
Cette fonctionnalité est-elle implémentée? visualstudio.uservoice.com/forums/121579-visual-studio/…
hellboy
Comment puis-je faire en sorte qu'Atomineer Pro laisse générer la balise de documentation <inheritDoc /> pour l'implémentation si la documentation pour l'interface est disponible?
hellboy
3
Vous avez raison <inheritdoc/>est cassé dans Visual Studio. Veuillez voter pour le rapport de bogue sur visualstudio.uservoice.com/forums/121579-visual-studio
Colonel Panic

Réponses:

62

Vous pouvez le faire assez facilement en utilisant la inheritdocbalise Microsoft Sandcastle (ou NDoc) . Ce n'est pas officiellement pris en charge par la spécification, mais les balises personnalisées sont parfaitement acceptables, et Microsoft a en effet choisi de copier cela (et une ou deux autres balises) à partir de NDoc lors de la création de Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Voici la page d'aide de l'interface graphique de Sandcastle Help File Builder, qui décrit son utilisation dans son intégralité.

(Bien sûr, il ne s'agit pas spécifiquement de "synchronisation", comme le mentionne votre question, mais il semblerait que ce soit exactement ce que vous recherchez.)

En guise de note, cela me semble être une idée parfaitement juste, même si j'ai observé que certaines personnes pensent que vous devriez toujours respécifier les commentaires dans les classes dérivées et implémentées. (En fait, je l'ai fait moi-même en documentant l'une de mes bibliothèques et je n'ai vu aucun problème.) Il n'y a presque toujours aucune raison pour que les commentaires diffèrent du tout, alors pourquoi ne pas simplement hériter et le faire de manière simple?

Edit: En ce qui concerne votre mise à jour, Sandcastle peut également s'en occuper pour vous. Sandcastle peut produire une version modifiée du fichier XML réel qu'il utilise pour l'entrée, ce qui signifie que vous pouvez distribuer cette version modifiée avec votre DLL de bibliothèque au lieu de celle construite directement par Visual Studio, ce qui signifie que vous avez les commentaires dans intellisense ainsi que le fichier de documentation (CHM, peu importe).

Noldorin
la source
Hé, c'est plutôt sympa! J'aime Sandcastle!
Tor Haugen
Publication modifiée pour répondre à la question mise à jour.
Noldorin
2
cela peut-il être fait au niveau de la classe? pour ne pas avoir à mettre /// <inheritdoc /> avant chaque méthode.
Antony Scott
1
Une chose que j'ai remarquée est qu'elle <inheritdoc/> n'hérite pas de la documentation de la <param>balise.
stephen
1
Votez cette fonctionnalité vocale utilisateur pour que <inheritdoc /> soit officiellement ajouté à la spécification C # et travaillez avec VS intellisense visualstudio.uservoice.com/forums/121579-visual-studio/…
deadlydog
14

Si vous ne l'utilisez pas déjà, je vous recommande fortement un addon Visual Studio gratuit appelé GhostDoc . Cela facilite le processus de documentation. Jetez un œil à mon commentaire sur une question quelque peu connexe.

Bien que GhostDoc n'effectue pas la synchronisation automatiquement, il peut vous aider dans le scénario suivant:

Vous disposez d'une méthode d'interface documentée. Implémentez cette interface dans une classe, appuyez sur la touche de raccourci GhostDoc Ctrl-Shift-D, et le commentaire XML de l'interface sera ajouté à la méthode implémentée.

Allez dans Options -> Paramètres du clavier et attribuez une touche à GhostDoc.AddIn.RebuildDocumentation(j'ai utilisé Ctrl-Shift-Alt-D). texte alternatif

Maintenant, si vous modifiez le commentaire XML sur l' interface , appuyez simplement sur cette touche de raccourci sur la méthode implémentée, et la documentation sera mise à jour. Malheureusement, cela ne fonctionne pas vice-versa.

Igal Tabachnik
la source
La dernière version (5.3.16270) de GhostDoc peut également créer des docu hérités. Je viens de l'essayer pour mes implémentations d'interface. Joli bonus, il ajoute aussi les exceptions avec le message de l'exception levée :-)
Christoph
6

J'écris généralement des commentaires comme celui-ci:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Les méthodes ne sont utilisées que par l'interface, donc ce commentaire n'est même pas affiché dans les info-bulles lors du codage.

Éditer:

Si vous voulez voir des documents lorsque vous appelez directement la classe et n'utilisez pas l'interface, vous devez l'écrire deux fois ou utiliser un outil comme GhostDoc.

Stefan Steinegger
la source
4

Essayez GhostDoc ! Ça marche pour moi :-)

Edit: Maintenant que j'ai été mis au courant du soutien de Sandcastle <inheritdoc/>, j'approuve le post de Noldorin. C'est une bien meilleure solution. Cependant, je recommande toujours GhostDoc de manière générale.

Tor Haugen
la source
6
Personnellement, je n'aime pas GhostDoc. Il génère de la documentation là où il n'y en a pas. Cela cache le fait que quelque chose n'est pas documenté. Juste une opinion personnelle, je ne dis pas que c'est quelque chose de mauvais en général.
Stefan Steinegger
1
D'accord avec le commentaire de Stefan en ce que GhostDoc n'est pas parfait, mais il récupère automatiquement des commentaires "hérités" comme celui-ci, donc c'est une assez bonne réponse à la question.
Steve
Stefan, je ne suis pas d'accord - au contraire, parce que GhostDoc ne reflète que la documentation que vous avez déjà "mise" dans vos noms de membres (en construisant de la prose à partir des noms), il ne génère de la documentation que là où la documentation existe déjà (implicitement). En tant que tel, il ne «produit» rien, mais la prose générée est un excellent point de départ auquel vous pouvez ajouter une valeur réelle. La vraie documentation demande encore du travail.
Tor Haugen
2

J'ai une meilleure réponse: FiXml . , Je suis l'un de ses auteurs

Le clonage est certainement une approche efficace, mais elle présente des inconvénients importants, par exemple:

  • Lorsque le commentaire d'origine est modifié (ce qui se produit fréquemment pendant le développement), son clone ne l'est pas.
  • Vous produisez une énorme quantité de doublons. Si vous utilisez des outils d'analyse de code source (par exemple Duplicate Finder dans Team City), il trouvera principalement vos commentaires.

Comme il a été mentionné, il existe une <inheritdoc>balise dans Sandcastle , mais elle présente peu d'inconvénients par rapport à FiXml:

  • Sandcastle produit des fichiers d'aide HTML compilés - normalement, il ne modifie pas les .xmlfichiers contenant des commentaires XML extraits (enfin, cela ne peut pas être fait "à la volée" pendant la compilation).
  • La mise en œuvre de Sandcastle est moins puissante. Par exemple, le n'est pas <see ... copy="true" />.

Voir la <inheritdoc>description de Sandcastle pour plus de détails.

Brève description de FiXml: il s'agit d'un post-processeur de documentation XML produit par C # \ Visual Basic .Net. Il est implémenté en tant que tâche MSBuild, il est donc assez facile de l'intégrer à n'importe quel projet. Il aborde quelques cas ennuyeux liés à l'écriture de documentation XML dans ces langages:

  • Pas de support pour hériter de la documentation de la classe de base ou de l'interface. C'est-à-dire qu'une documentation pour tout membre surchargé doit être écrite à partir de zéro, bien que normalement, il soit tout à fait souhaitable d'en hériter au moins une partie.
  • Aucune prise en charge pour l'insertion de modèles de documentation couramment utilisés , tels que "Ce type est singleton - utilisez sa <see cref="Instance" />propriété pour en obtenir la seule instance.", Ou même "Initialise une nouvelle instance de <CurrentType>classe."

Pour résoudre les problèmes mentionnés, les balises XML supplémentaires suivantes sont fournies:

  • <inheritdoc />, <inherited /> Mots clés
  • <see cref="..." copy="..." />attribut dans la <see/>balise.

Voici sa page Web et sa page de téléchargement .

Alex Yakunin
la source
1

J'ai construit une bibliothèque pour post-traiter les fichiers de documentation XML afin d'ajouter la prise en charge de la balise <inheritdoc />.

Bien que cela n'aide pas avec Intellisense dans le code source, il permet aux fichiers de documentation XML modifiés d'être inclus dans un package NuGet et fonctionne donc avec Intellisense dans les packages NuGet référencés.

Plus d'informations sur www.inheritdoc.io (version gratuite disponible).

K Johnson
la source
0

Ne fais pas ça. Pensez-y de cette façon - si les deux commentaires doivent être les mêmes tout le temps, alors l'un d'eux n'est pas nécessaire. Il doit y avoir une raison pour le commentaire (en plus d'une sorte d'obligation étrange de bloquer les commentaires sur chaque fonction et variable), vous devez donc déterminer quelle est cette raison unique et la documenter.

1800 INFORMATIONS
la source
3
Je n'aurais pas utilisé l'interface ici si je ne l'avais pas simulée lors de tests.
Valentin Vasilyev
0

Avec ReSharper, vous pouvez le copier, mais je ne pense pas qu'il soit synchronisé tout le temps.

crauscher
la source