XML Comentando sobre clases/métodos parciales

Question

¿Hay alguna manera estándar en que las herramientas utilizadas para generar los documentos API manejen tener comentarios de estilo XML en clases parciales? Básicamente, ¿cómo se debe comentar una clase/método parcial para que los documentos de ayuda resultantes no se alteren? Esta pregunta podría variar dependiendo de la herramienta que se utiliza, en cuyo caso, supongo que las dos herramientas que son los más importantes son:

• Visual construida en el método para crear la documentación XML Estudio
• de Microsoft castillo de arena

yo no quiero que mi documentación XML para salir cobarde es todo

/// <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 mejor práctica es dar a los comentarios XML solo 1 de las definiciones parciales. No debería haber necesidad de dividir los comentarios públicos para 1 clase en 2 lugares.

La manera en que funciona Visual Studio es que un comentario anulará al otro. (Puede confirmar esto creando 2 definiciones parciales de la misma clase con diferentes comentarios XML, luego cree una variable de este tipo. El intellisense mostrará solo 1 de los comentarios XML.)

Este también será el comportamiento de cualquier herramienta de documentación que use el archivo de comentarios XML generado por Visual Studio, que incluye Sandcastle.