O que devo incluir nos comentários da documentação XML?

Estou tentando documentar melhor meu código, especialmente quando se trata de comentários XML sobre os membros da classe, mas muitas vezes parece bobagem.

No caso de manipuladores de eventos, a convenção de nomenclatura e os parâmetros são padrão e 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...
}

Também frequentemente tenho propriedades simples que são (IMO) nomeadas claramente para que o resumo seja redundante:

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

Eu não acho que esses comentários não adicionem nenhuma informação que a declaração em si ainda não transmita. A sabedoria geral parece ser que um comentário que repete o código é melhor não ser escrito.

Obviamente, a documentação XML é mais do que apenas comentários regulares de código embutido e, idealmente, terá 100% de cobertura. O que devo escrever nesses casos? Se esses exemplos estão corretos, que valor eles acrescentam que talvez eu não esteja gostando agora?

Os comentários de documentos XML destinam-se a membros públicos.

O aviso do compilador afirma claramente isso:

Comentário XML ausente para o tipo ou membro publicamente visível 'Type_or_Member'

Você só deve adicionar comentários XML a membros privados se esses membros ainda não estiverem evidentes em seus nomes.

Pura opinião aqui, então aceite pelo que vale a pena.

Eu odeio comentários xml supérfluos. Duplamente para os fantasmas no estilo doc, que simplesmente adicionam espaços ao nome do método / propriedade. Não agrega valor e simplesmente atrapalha minha visão do código real.

Se algo precisar de esclarecimento, com certeza, comente. No entanto, muita clareza pode ser transmitida por pequenos métodos focados com nomes significativos. Não comente o código se puder melhorá-lo e tornar o comentário desnecessário.

Nem me inicie no uso desnecessário this.eMe. .

Como uma observação lateral, eu adoraria ter um complemento do Visual Studio que permita alternar a visibilidade dos comentários xml. (dica, dica)

Em um membro público, os documentos XML devem ser bastante detalhados e completos, como o @SLaks mencionou.

No entanto, eles também podem ser realmente úteis para membros privados, protegidos ou internos, porque o Visual Studio preencherá o intellisense e ajudará as dicas de ferramentas com os comentários dos documentos XML.

Isso significa que:

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

Pode ser documentação perfeitamente suficiente, mas:

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

Será muito mais fácil ver rapidamente de outras partes do seu código.

Geralmente nos comentários XML públicos que estou escrevendo para algum usuário externo da API e nos comentários XML internos que estou escrevendo para mim ou para outros membros da minha equipe.

Ignorar descrições de parâmetros é provavelmente uma má ideia para o primeiro e bom para o último.

Eu acrescentaria (principalmente nos documentos públicos da API) sempre incluir getou não as setpropriedades:

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

Não é óbvio pelo intellisense do C # se está disponível getou setnão, mas colocá-lo no comentário XML significa que você pode ver rapidamente a dica de ferramenta.