Existe-t-il un moyen préféré de documenter les méthodes implémentant une interface?

Question

Je me demande s'il y a un moyen de le faire, ou même si cela devrait être fait? Mes pensées sont vite allées à l'utilisation des attributs de la méthode car c'est une sorte de métadonnées, mais je ne suis pas sûr qu'il y en ait pour cela. À l'heure actuelle, j'utilise simplement les balises <remark> du commentaire XML pour savoir quand une méthode implémente une interface. Mais ce n'est bien sûr pas une forme structurée de métadonnées. Peut-être que les systèmes de documentation de code automatisés peuvent déjà analyser ces informations à travers le code, mais il pourrait être utile pour quiconque lisant le code actuel de le suivre plus facilement.

Answer 1

Si vous voulez dire quelque chose comme une liste de classes qui implémentent une interface, vous pouvez utiliser la balise <seealso> de l'en-tête de la documentation.

/// <summary> 
/// Interface that AutoCAD commands are required to implement. 
/// </summary> 
/// <seealso cref="My.Namespace.ClassThatImplementsThisInterface"/> 
/// <seealso cref="My.Namespace.AnotherClassThatImplementsThisInterface"/> 
public interface IMyInterface 

Vous pouvez aussi le faire sur une méthode de se référer à la méthode d'interface:

public class ClassThatImplementsThisInterface : IMyInterface 
{ 
    /// <summary> 
    /// </summary> 
    /// <seealso cref="My.Namespace.IMyInterface.InterfaceMethod" /> 
    public void InterfaceMethod() 
    { 
    } 
} 

Je n'ai jamais utilisé un générateur de documentation en C# et ne pas utiliser les méthodes ci-dessus à le temps donc je ne peux pas le dire pour acquis, mais je crois que les générateurs devraient ramasser ces références et créer un lien dans la documentation à la méthode/classe/interface référencée.

Answer 2

Découvrez GhostDoc. C'est un plugin de studio visuel gratuit. Il a un menu et des raccourcis clavier faciles à générer automatiquement les commentaires de la documentation. Il sera également assez intelligent pour déduire certaines fonctionnalités des noms de méthodes. Par exemple, si vous avez une méthode telle que "public void SavePerson()", lorsque vous êtes dans la méthode, vous appuyez sur Ctrl + Maj + D pour générer les commentaires pré-remplis avec quelque chose comme "cette méthode est utilisée pour enregistrer une personne".

Si votre classe implémente une interface, elle le documentera également. Si vos méthodes prennent des paramètres, elles se référeront à ces types. Vous aurez toujours besoin de taper beaucoup de texte pour ajouter de la valeur à ce que votre classe/méthode/propriété fait réellement, mais GhostDoc est un excellent moyen de générer l'échafaudage de base, les références croisées, la hiérarchie d'héritage et les détails d'interface dans documentation de code.