Façons de synchroniser l’interface et les commentaires d’implémentation en C #

Vous pouvez le faire facilement en utilisant la balise 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 ceci (et un ou deux autres balises) à partir de NDoc quand ils ont créé Sandcastle.

 ///  ///  /// You can still specify all the normal XML tags here, and they will /// overwrite inherited ones accordingly. ///  public void MethodImplementingInterfaceMethod(ssortingng 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, ce n’est pas spécifiquement la “synchronisation”, comme votre question le mentionne, mais cela semble être exactement ce que vous recherchez néanmoins.)

Comme une note, cela semble être une idée tout à fait juste pour moi, même si j’ai observé que certaines personnes pensent que vous devriez toujours redéfinir les commentaires dans les classes dérivées et implémentées. (Je l’ai déjà fait moi-même en documentant 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, alors pourquoi ne pas simplement hériter et le faire facilement?

Edit: En ce qui concerne votre mise à jour, Sandcastle peut également en prendre soin pour vous. Sandcastle peut générer une version modifiée du fichier XML réel utilisé pour l’entrée, ce qui signifie que vous pouvez dissortingbuer cette version modifiée avec votre DLL de bibliothèque au lieu de celle créée directement par Visual Studio, ce qui signifie que vous avez les commentaires dans intellisense ainsi que le fichier de documentation (CHM, peu importe).

Si vous ne l’utilisez pas déjà, je recommande fortement un addon gratuit Visual Studio appelé GhostDoc . Cela facilite le processus de documentation. Regardez mon commentaire sur une question un peu reliée.

Bien que GhostDoc ne procède pas automatiquement à la synchronisation, il peut vous aider avec le scénario suivant:

Vous avez 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 atsortingbuez une clé à GhostDoc.AddIn.RebuildDocumentation (j’ai utilisé Ctrl-Shift-Alt-D ). alt text http://soffr.miximages.com/c%23/10dd1f9.png

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.

J’écris habituellement des commentaires comme ceci:

 /// 
 /// Implements  /// 
 ///  

Les méthodes ne sont utilisées que par l’interface. Ce commentaire n’est donc pas affiché dans les info-bulles lors du codage.

Modifier:

Si vous voulez voir des documents lorsque vous appelez directement la classe sans utiliser l’interface, vous devez l’écrire deux fois ou utiliser un outil tel que GhostDoc.

Essayez GhostDoc ! Ça marche pour moi 🙂

Edit: Maintenant que j’ai été informé du support de Sandcastle pour , le post de Noldorin. C’est une solution bien meilleure. Je recommande toujours GhostDoc sur une base générale, cependant.

J’ai une meilleure réponse: FiXml .

Le clonage est certainement une approche de travail, mais il présente des inconvénients importants, par exemple:

• Lorsque le commentaire d’origine est modifié (ce qui arrive fréquemment au cours du développement), son clone ne l’est pas.
• Vous produisez beaucoup de doublons. Si vous utilisez des outils d’parsing de code source (par exemple, Duplicate Finder dans Team City), il trouvera principalement vos commentaires.

Comme cela a été mentionné, il existe une 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 .xml fichiers .xml 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 is no .

Voir la description de Sandcastle pour plus de détails.

Brève description de FiXml: c’est 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:

• Aucun support pour hériter de la documentation de la classe de base ou de l’interface. C’est-à-dire qu’une documentation pour un membre surchargé devrait être écrite à partir de zéro, bien qu’il soit normalement 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 pour en obtenir la seule instance.”, Ou même “Initialise une nouvelle instance de cours.

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

• ,
• atsortingbut dans la .

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

 ///  

Lire ici

Utilisez ceci

J’ai construit une bibliothèque pour post-traiter les fichiers de documentation XML afin d’append le support de la balise .

Bien qu’il ne soit pas utile 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’infos sur http://www.inheritdoc.io (version gratuite disponible).

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

Ne fais pas ça. Pensez-y de cette façon – si les deux commentaires doivent être identiques tout le temps, 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 chaque fonction et variable) afin que vous trouviez cette raison unique et la documentez.