Що я повинен включати в коментарі до документації 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. Подвійно для стилів doc doc, які просто додають пробіли до імені методу / властивості. Це не додає ніякого значення і просто забиває мій погляд на фактичний код.

Якщо щось потребує роз'яснення, будь-ласка, прокоментуйте це. Однак багато ясності можна передати невеликими цілеспрямованими методами зі змістовними назвами. Не коментуйте код, якщо ви можете його покращити і зробити коментар непотрібним.

Навіть не пускайте мене на непотрібне використання this.та Me..

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

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

Однак вони можуть бути дуже корисними і для приватних, захищених або внутрішніх членів, оскільки Visual Studio заповнить інтелігенцію та допоможе підказки з коментарями 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; } 
}

З інтелігенції C # не очевидно, getчи setє, чи є, але розміщення його на коментарі XML означатиме, що ви можете сказати з першого погляду з підказки.