XML commentant les classes / méthodes partielles

Question

Existe-t-il un moyen standard que les outils utilisés pour générer les documents API gèrent les commentaires de style XML sur les classes partielles? Fondamentalement, comment doit commenter une classe / méthode partielle afin que les documents d'aide résultants ne soient pas mutilés? Cette question pourrait varier en fonction de l'outil utilisé, auquel cas, je suppose que les deux outils les plus importants sont:

• Méthode intégrée de Visual Studio pour créer une documentation XML
• Le château de sable de Microsoft

Je ne veux pas que ma documentation XML sort funky est tout

/// <summary>Some Foo class</summary>
public partial class Foo { ... }

/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }

Answer 1

La meilleure pratique consiste à donner des commentaires XML à Juste une des définitions partielles. Il ne devrait pas y avoir besoin de se séparer Publique Commentaires pour 1 classe en 2 endroits. (Bien sûr, les commentaires réguliers ont toujours du sens d'avoir dans chaque définition partielle.)

La façon dont Visual Studio fonctionne est qu'un commentaire dans une définition partielle remplacera l'autre. Vous pouvez confirmer cela en créant 2 définitions partielles de la même classe avec différents commentaires XML, puis créez une variable de ce type. L'Intellisense ne montrera que 1 des commentaires XML.

Ce sera également le comportement de tout outil de documentation qui utilise le fichier de commentaires XML généré par Visual Studio, qui comprend Sandcastle.