c# - valid - XML comentando sobre clases/métodos parciales

remarks c#

Question

¿Hay alguna forma estándar en que las herramientas utilizadas para generar los documentos de la 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 dañen? Esta pregunta puede variar según la herramienta utilizada, en cuyo caso, supongo que las dos herramientas que son las más importantes son:

• El método incorporado de Visual Studio para crear documentación XML
• Castillo de arena de Microsoft

No quiero que mi documentación XML salga de moda 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 comentarios XML a solo 1 de las definiciones parciales . No debería haber necesidad de dividir los comentarios públicos para 1 clase en 2 lugares. (Por supuesto, los comentarios regulares todavía tienen sentido en cada definición parcial.)

La forma en que funciona Visual Studio es que un comentario en una definición parcial reemplazará a la otra. 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.