¿Qué debo incluir en los comentarios de la documentación XML?

Estoy tratando de documentar mejor mi código, especialmente cuando se trata de los comentarios XML en los miembros de la clase, pero a menudo se siente tonto.

En el caso de los controladores de eventos, la convención de nombres y los parámetros son estándar y claros:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

También con frecuencia tengo propiedades simples que (IMO) se nombran claramente para que el resumen sea redundante:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

No creo que tales comentarios no agreguen ninguna información que la declaración en sí misma no transmita. La sabiduría general parece ser que un comentario que repite el código es mejor dejarlo sin escribir.

Obviamente, la documentación XML es más que solo comentarios regulares de código en línea, e idealmente tendrá una cobertura del 100%. ¿Qué debería estar escribiendo en tales casos? Si estos ejemplos son correctos, ¿qué valor agregan que quizás no aprecie ahora?

Los comentarios de documentos XML están destinados a miembros públicos.

La advertencia del compilador establece claramente esto:

Falta el comentario XML para el tipo o miembro visible públicamente 'Type_or_Member'

Solo debe agregar comentarios XML a miembros privados si esos miembros aún no son obvios por sus nombres.

Pura opinión aquí, así que tómalo por lo que vale.

Yo odio los comentarios superfluos XML. Doblemente para los fantasmas de estilo doc que simplemente agregan espacios al método / nombre de propiedad. No agrega valor y simplemente satura mi vista del código real.

Si algo necesita aclaración, por supuesto, coméntalo. Sin embargo, se puede transmitir mucha claridad mediante pequeños métodos enfocados con nombres significativos. No comente el código si puede mejorarlo y haga que el comentario sea innecesario.

Ni siquiera me hagas comenzar con el uso innecesario de this.y Me..

Como nota al margen, me encantaría tener un complemento de Visual Studio que me permita alternar la visibilidad de los comentarios xml. (pista Pista)

En un miembro público, los documentos XML deben ser bastante detallados y completos, como ha mencionado @SLaks.

Sin embargo, también pueden ser realmente útiles en miembros privados, protegidos o internos porque Visual Studio rellenará intellisense y ayudará a la información sobre herramientas con los comentarios del documento XML.

Esto significa que:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Podría ser documentación perfectamente suficiente, pero:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Será mucho más fácil verlo rápidamente desde otra parte de su código.

En general, en los comentarios XML públicos que escribo para algún usuario externo de la API, y en los comentarios XML internos que escribo para mí u otros miembros de mi equipo.

Saltar las descripciones de los parámetros es probablemente una mala idea para el primero y está bien para el segundo.

Yo agregaría (especialmente en documentos públicos de API) siempre incluiría si geto seten propiedades:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

No es obvio por la inteligencia de C # si está disponible geto setno, pero ponerlo en el comentario XML significará que puede verlo de un vistazo a partir de la información sobre herramientas.