web-dev-qa-db-fra.com

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

Existe-t-il des moyens automatiques de synchroniser les commentaires entre une interface et son implémentation? Je suis actuellement en train de les documenter tous les deux et je ne voudrais pas les garder synchronisés manuellement.

MISE À 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 ça:

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

Le <inheritDoc/> tag générera parfaitement la documentation dans Sand Castle, mais cela ne fonctionne pas dans les info-bulles intellisense.

Veuillez partager vos idées.

Merci.

c#documentationxml-documentation
88
Valentin

Vous pouvez le faire assez facilement en utilisant la balise Microsoft Sandcastle (ou NDoc) inheritdoc. 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)
{
    //
}

ici est 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 néanmoins être exactement ce que vous recherchez.)

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

Edit: Concernant votre mise à jour, Sandcastle peut également s'en occuper pour vous. Sandcastle peut sortir 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 bibliothèque DLL au lieu de la celui construit directement par Visual Studio, ce qui signifie que vous avez les commentaires dans intellisense ainsi que le fichier de documentation (CHM, peu importe).

57
Noldorin

Si vous ne l'utilisez pas déjà, je recommande fortement un module complémentaire Visual Studio gratuit appelé GhostDoc . Il facilite le processus de documentation. Jetez un oeil à 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.

Accédez aux paramètres Options -> Clavier et attribuez une touche à GhostDoc.AddIn.RebuildDocumentation (J'ai utilisé Ctrl-Shift-Alt-D). alt text

Maintenant, si vous modifiez le commentaire XML sur 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.

11
Igal Tabachnik

J'écris habituellement des commentaires comme celui-ci:

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

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

Modifier:

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

5
Stefan Steinegger

Essayez GhostDoc ! Ça marche pour moi :-)

Edit: Maintenant que j'ai été informé du support de Sandcastle pour <inheritdoc/>, J'approuve le post de Noldorin. C'est une bien meilleure solution. Je recommande néanmoins GhostDoc sur une base générale.

4
Tor Haugen

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

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

  • Lorsque le commentaire d'origine est modifié (ce qui arrive 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 cela a été mentionné, il y a <inheritdoc> tag in Sandcastle, mais il présente quelques inconvénients par rapport à FiXml:

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

Voir Sandcastle's <inheritdoc> description 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 résout quelques cas gênants liés à l'écriture de documentation XML dans ces langues:

  • Pas de prise en charge de l'héritage de la documentation de la classe de base ou de l'interface. I.e. une documentation pour tout membre remplacé doit être écrite à partir de zéro, bien que normalement il soit tout à fait souhaitable d’en hériter au moins une partie.
  • Pas de prise en charge pour l'insertion de modèles de documentation couramment utilisés , tels que "Ce type est singleton - utilisez son <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 <see/> tag.

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

2
Alex Yakunin

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 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).

1
K Johnson
/// <inheritDoc/>

Lire ici

tilisez ceci

1
Krzysztof Kozmic

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

0
crauscher

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 bizarre de bloquer les commentaires de chaque fonction et variable), vous devez donc comprendre quelle est cette raison unique et la documenter.

0
1800 INFORMATION