我应该在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文档注释供公共成员使用。

该编译器警告明确指出这一点：

公开类型或成员'Type_or_Member'的XML注释丢失

仅当私有成员的名称不明显时，才应将它们添加到私有成员中。

在这里纯粹是意见，因此请考虑它的价值。

我讨厌多余的xml注释。对于只在方法/属性名称中添加空格的“幽灵”文档样式而言，这是令人怀疑的。它没有任何价值，只会使我对实际代码的看法变得混乱。

如果确实需要澄清，请对其进行评论。但是，可以通过一些名称有意义的小型聚焦方法来传达许多清晰度。如果可以改进代码，并且不必添加注释，请不要注释代码。

甚至不要让我开始不必要地使用this.和Me.。

附带说明一下，我很想拥有一个Visual Studio插件，让我可以切换xml注释的可见性。（提示提示）

正如@SLaks所提到的，在公开成员上，XML文档应该相当详细和完整。

但是，它们对于私有成员，受保护成员或内部成员也非常有用，因为Visual Studio会使用XML doc注释填充智能感知和帮助工具提示。

这意味着：

// 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注释将意味着你可以从提示一眼就能看出。