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 docコメントは、公開メンバーを対象としています。

コンパイラの警告は、これを明確に述べています：

一般公開されているタイプまたはメンバー「Type_or_Member」のXMLコメントがありません

プライベートメンバーにXMLコメントを追加する必要があるのは、それらのメンバーが名前から明らかでない場合のみです。

ここでは純粋な意見ですので、それが価値があると考えてください。

余分なxmlコメントは嫌いです。メソッド/プロパティ名にスペースを追加するだけのゴーストドキュメントスタイルの場合は二重です。それは価値を追加せず、単に実際のコードの私の見解を混乱させます。

何か明確にする必要がある場合は、必ずコメントしてください。ただし、意味のある名前の小さな焦点を絞った方法によって、多くの明確さが伝わります。コードを改善してコメントを不要にできる場合は、コードにコメントを付けないでください。

でも私は、不要の使用を開始してはいけないthis.とMe.。

副次的な注意事項として、XMLコメントの可視性を切り替えることができるVisual Studioアドインが必要です。（ヒントヒント）

@SLaksが述べたように、公開メンバーでは、XMLドキュメントはかなり冗長で完全でなければなりません。

ただし、Visual Studioがインテリセンスを生成し、XMLドキュメントコメントでツールチップを支援するため、プライベートメンバー、保護メンバー、または内部メンバーでも非常に役立ちます。

この意味は：

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

完全に十分なドキュメントかもしれませんが、次のとおりです。

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

コードのどこからでもすぐに見やすくなります。

一般に、私はAPIの外部ユーザー向けに書いているパブリックXMLコメント、および私やチームの他のユーザー向けに書いている内部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コメントに含めると、ツールチップから一目でわかるようになります。