XML commentando classi/metodi parziali

Question

Esiste un modo standard che gli strumenti utilizzati per generare i documenti API gestiscono con commenti in stile XML su classi parziali? Fondamentalmente, come si dovrebbe commentare una classe/metodo parziale in modo che i documenti di aiuto risultante non siano mangeli? Questa domanda potrebbe variare a seconda dello strumento utilizzato, nel qual caso, immagino che i due strumenti più importanti siano:

• Metodo integrato di Visual Studio per creare la documentazione XML
• Microsoft's Sandcastle

Non voglio che la mia documentazione XML esca funky è tutto

/// <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 migliore pratica è dare commenti XML a solo 1 delle definizioni parziali. Non dovrebbe essere necessario dividere pubblico Commenti per 1 classe in 2 luoghi. (Naturalmente commenti regolari hanno ancora senso avere in ogni definizione parziale.)

Il modo in cui funziona Visual Studio è che un commento in una definizione parziale sovrascriverà l'altra. Puoi confermarlo creando 2 definizioni parziali della stessa classe con diversi commenti XML, quindi creare una variabile di questo tipo. L'intellisense mostrerà solo 1 dei commenti XML.

Questo sarà anche il comportamento di qualsiasi strumento di documentazione che utilizza il file dei commenti XML generato da Visual Studio, che include Sandcastle.