practices - generate documentation c#

El propósito de usar las etiquetas<valor> y<summary> en la documentación de Visual Studio XML

Question

Estoy trabajando en C # en VS 2012, agregando documentación XML a mi código, y accidentalmente activé una regla StyleCop (SA1609, específicamente), que "valida que una propiedad pública o protegida contenga un encabezado de documentación con una etiqueta de valor ".

También hay otra regla (SA1604, activada intencionalmente esta vez), que "valida que un encabezado de documentación contenga una etiqueta de resumen con el formato correcto".

Sin embargo, estoy luchando para ver lo que pondrías en la etiqueta de valor que aún no está en la etiqueta de resumen . Actualmente mis etiquetas de resumen dicen algo como "Obtiene o establece algo". ¿Qué se debe poner en la etiqueta de valor correspondiente para complementar eso?

(Solo para aclarar, estoy contento con la configuración de StyleCop, me llamó la atención la etiqueta de valor cuando activé accidentalmente todas las reglas de documentación)

MSDN no está ayudando mucho con esto:

• La página de la etiqueta de valor parece implicar que debe detallar qué campo de respaldo se está utilizando (lo que parece una mala idea en el interés de ocultar información de todos modos).
• Su How-To en la documentación XML dice que "una etiqueta de valor se utiliza para describir el valor de la propiedad ". Ni siquiera estoy seguro de qué significa eso, me parece mucho el resumen.

tl; dr

¿Cuál es el punto de tener tanto etiquetas de resumen como de valor en la documentación XML para las propiedades? ¿Cómo se deben utilizar sin repetirse?

Answer 1

El resumen es para dar una visión general de lo que puede hacer la propiedad, mientras que el valor describe exactamente eso, qué valor esperar de la propiedad.

Este es un buen ejemplo de la diferencia en MSDN: List<T>.IList.IsFixedSize Property

Resumen: Obtiene un valor que indica si el IList tiene un tamaño fijo.

Valor: verdadero si el IList tiene un tamaño fijo; de lo contrario, falso. En la implementación predeterminada de la Lista <T>, esta propiedad siempre devuelve falso.

En su mayor parte, las etiquetas de resumen generalmente indicarán "Obtiene o establece un valor ..." , mientras que las etiquetas de valor generalmente indicarán qué valores esperar, incluido cuál se espera que sea el valor predeterminado.

Answer 2

Simplemente: esto hace que sea más fácil mantenerlos actualizados a medida que el código evoluciona.

Personalmente creo que agrega información más útil cuando el código debe ser modificado por otros autores.