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

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.

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

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

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

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.

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 .

/// <inheritDoc/>

Lisez ici

Utilisez ceci

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

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.

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