Commentaires xml appropriés sur l'interface .NET

Question

s'il existe une interface et une classe qui l'implémente et que vous voulez que le commentaire xml soit utilisé dans VS intellisense ou dans la documentation où placeriez-vous le commentaire xml? sur les méthodes de l'interface ou sur les méthodes de classe concrètes? Quelle est la bonne façon?

Mes pensées sont de le mettre dans l'interface parce que nous déclarons les variables en utilisant l'interface. Et je pense que c'est redondant si j'ai aussi mis un commentaire sur la classe concrète et que cela peut conduire à une documentation différente sur la même méthode.

Des idées, des conseils?

Answer 1

Vous devez documenter tout membre public. Si vous avez implémenté ISomeInterface.SomeMember sous la forme public void SomeMember, vous devez le documenter. Pour une chose, le lecteur verra cela comme faisant partie de votre classe, et seulement en lisant la documentation (qu'ils ne peuvent pas savoir regarder s'il n'est pas là) ils sauront qu'il est défini dans cette interface. Si c'est implémenté comme void ISomeInterface.SomeMember alors c'est moins important, car il ne sera pas vu comme faisant partie de l'interface publique de la classe.

Il est également parfois important de connaître les détails sur la manière dont votre classe particulière a implémenté un membre d'interface donné. D'autre part, il peut être raisonnable de donner une description très courte et de diriger les gens vers la documentation de l'interface pour plus de détails.