Comment synchroniser les commentaires d'interface et d'implémentation en C# ?

Question

Existe-t-il des moyens automatiques de synchroniser les commentaires entre une interface et son implémentation ? Je suis en train de documenter les deux et je n'aimerais pas les synchroniser manuellement.

UPDATE :

Considérons ce code :

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}

class Foo : IFoo {
    public void DoThis();
}

Lorsque 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

En <inheritDoc/> génère parfaitement la documentation dans Sand Castle, mais ne fonctionne pas dans les infobulles d'intellisense.

Answer 1

Vous pouvez le faire très facilement à l'aide de Microsoft Sandcastle (ou NDoc) inheritdoc tag. Elle n'est pas officiellement prise en charge par la spécification, mais les balises personnalisées sont parfaitement acceptables. Microsoft a d'ailleurs choisi de copier cette balise (et une ou deux autres) de NDoc lorsqu'il a créé 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 du Sandcastle Help File Builder GUI, qui décrit son utilisation en détail.

(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 néanmoins).

J'ai cependant observé que certaines personnes pensent qu'il faut toujours respécifier les commentaires dans les classes dérivées et implémentées. (Je l'ai moi-même fait en documentant l'une de mes bibliothèques et je n'ai constaté aucun problème). Il n'y a presque jamais de raison pour que les commentaires diffèrent, alors pourquoi ne pas simplement hériter et faire les choses facilement ?

Edita: En ce qui concerne votre mise à jour, Sandcastle peut également s'en charger pour vous. Sandcastle peut produire une version modifiée du fichier XML qu'il utilise en entrée, ce qui signifie que vous pouvez distribuer les fichiers suivants cette version modifiée avec votre bibliothèque DLL 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).

Answer 2

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

Bien que GhostDoc n'effectue pas la synchronisation automatiquement, il peut vous aider dans le cas 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 mise en œuvre.

Aller à la page Options -> Clavier et assigner une touche à GhostDoc.AddIn.RebuildDocumentation (J'ai utilisé Ctrl-Shift-Alt-D ).

Maintenant, si vous modifiez le commentaire XML sur le fichier interface Il suffit d'appuyer sur cette touche de raccourci sur la méthode mise en œuvre pour que la documentation soit mise à jour. Malheureusement, cela ne fonctionne pas dans l'autre sens.

Answer 3

J'ai l'habitude d'écrire 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, de sorte que ce commentaire n'apparaît même pas dans les infobulles lors du codage.

Edita:

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

Answer 4

Essayer GhostDoc ! Cela fonctionne pour moi :-)

Edita: Maintenant que j'ai été informé du soutien apporté par Sandcastle au programme <inheritdoc/> Je suis d'accord avec le message de Noldorin. C'est une bien meilleure solution. Je continue cependant à recommander GhostDoc d'une manière générale.

Answer 5

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 original est modifié (ce qui arrive fréquemment au cours du développement), son clone ne l'est pas, son clone ne l'est pas.
• Vous produisez un grand nombre de doublons. Si vous utilisez un outils d'analyse du code source (par exemple, Duplicate Finder dans Team City), il trouvera principalement vos commentaires.

Comme il a été mentionné, il y a <inheritdoc> étiquette dans Château de sable mais il présente peu d'inconvénients par rapport à FiXml :

• Sandcastle produit des fichiers d'aide HTML compilés - normalement, il ne modifie pas les fichiers d'aide. .xml les 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, il n'y a pas de <see ... copy="true" /> .

Voir Châteaux de sable <inheritdoc> description pour plus de détails.

Brève description de FiXml : il s'agit d'un post-traitement de la documentation XML produite par C# ou 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 traite quelques cas gênants liés à l'écriture de documentation XML dans ces langages :

• Pas de prise en charge de l'héritage de la documentation à partir d'une classe de base ou d'une interface. En d'autres termes, une documentation pour tout membre surchargé doit être rédigée à partir de zéro, bien qu'il soit normalement souhaitable d'hériter au moins d'une partie de ce membre.
• Pas de support pour l'insertion de modèles de documentation couramment utilisés comme "Ce type est un singleton - utilisez son <see cref="Instance" /> pour obtenir la seule instance de celle-ci", ou encore "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 /> étiquettes
• <see cref="..." copy="..." /> dans l'attribut <see/> étiquette.

Voici sa page web y page de téléchargement .