Что я должен включить в комментарии к документации XML?

Я пытаюсь лучше документировать свой код, особенно когда речь идет о XML-комментариях к ученикам, но часто это кажется глупым.

В случае обработчиков событий соглашение об именах и параметры стандартны и понятны:

/// <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...
}

У меня также часто бывают простые свойства, которые (IMO) названы четко, так что сводка избыточна:

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

Я не думаю, что такие комментарии не добавляют никакой информации, которую сама декларация уже не передает. Общая мудрость, кажется, состоит в том, что комментарий, который повторяет код, лучше оставить неписанным.

Очевидно, что документация XML - это больше, чем просто комментарии встроенного кода, и в идеале она будет охватывать 100%. Что должен я быть писать в таких случаях? Если эти примеры в порядке, какую ценность они добавляют, что я, возможно, не оцениваю сейчас?

Комментарии в формате XML предназначены для публичных участников.

Предупреждение компилятора ясно говорит об этом:

Отсутствует комментарий XML для публично видимого типа или члена 'Type_or_Member'

Вы должны добавлять комментарии XML только к закрытым членам, если эти члены еще не очевидны из их имен.

Чистое мнение здесь, так что принимайте это за то, что оно стоит.

Я ненавижу лишние xml комментарии. Вдвойне для тех, кто использует ghost doc, которые просто добавляют пробелы к имени метода / свойства. Это не добавляет никакой ценности и просто загромождает мой взгляд на реальный код.

Если что-то требует уточнения, обязательно прокомментируйте это. Тем не менее, большая ясность может быть передана с помощью небольших целенаправленных методов со значимыми именами. Не комментируйте код, если вы можете улучшить его и сделать комментарий ненужным.

Даже не заводите меня на ненужное использование this.и Me..

Как примечание, я хотел бы иметь надстройку Visual Studio, которая позволяет мне переключать видимость комментариев xml. (Подсказка Подсказка)

На открытом члене XML-документы должны быть достаточно многословными и полными, как упомянул @SLaks.

Однако они могут быть действительно полезны для частных, защищенных или внутренних членов, потому что Visual Studio заполняет intellisense и помогает всплывающим подсказкам с комментариями документа XML.

Это означает, что:

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

Может быть вполне достаточно документации, но:

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

Намного легче будет быстро увидеть из другого места в вашем коде.

Как правило, для общедоступных комментариев XML я пишу для какого-то внешнего пользователя API, а для внутренних комментариев XML я пишу для меня или других членов моей команды.

Пропуск описаний параметров, вероятно, является плохой идеей для первого и хорошим для второго.

Я хотел бы добавить (в документации общественных API особенно) всегда включают ли getили setпо свойствам:

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

Из intellisense в C # не очевидно, доступны ли они getили setнет, но добавление их в комментарий XML будет означать, что вы можете сразу увидеть подсказку.