C＃XMLコメント：XMLコメント内の<see ... />参照はどれくらい便利ですか？

Question

当社では、過剰なXmlコメントを記述しています。典型的な方法はある。このように文書化する必要があります：あなたは<see cref>タグを使用して参照することができるほぼすべての名詞を見ることができるように

/// <summary> 
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param> 
/// <returns> 
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>. 
/// </returns> 
bool Contains(ISchedule schedule); 

/// <summary> 
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/> 
/// from this <see cref="IScheduler"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param> 
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception> 
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception> 
void Remove(ISchedule schedule); 

。
これはあまりにも多く見つかりました。私たちのコードファイルのほとんどは、そのようなコメントで爆破されています。コメントセクションをほとんど読めるようにします。

あなたはどう思いますか？このような種類の文書がコード内に好きですか？そうではありませんか？

いつものように、このような種類の質問には白黒の回答はないと思うので、私はそれをwikiにしました。

EDIT：
see-ref-tags自体がデフォルトで有効であれば私の質問はありませんでした。 .chmファイル（または他の種類の生成されたdocu）で生成されたリンクは非常に便利であることは明らかです。私の質問は、コメント内のすべての "リンク可能な"名詞が出現するたびにタグを付けることが本当に役立つかどうかということでした。
サンドキャッスルを使用して毎晩ドキュメントを生成します。残念ながら、それは他の開発者によって非常に珍しく使用されていますが、それは別の問題です。

Answer 1

サンドキャッスルのようなものがライブラリ用のHTMLまたはCHMドキュメントを生成するために使用されるとき、それらのドキュメントはオブジェクト間のハイパーリンクナビゲーションを取得するということです。したがって、MSDNを使用すると、そのクラスのヘルプに移動したクラス名をクリックすると便利なのですか？それをコピーして検索フィールドに貼り付けても問題ありませんか？

はい、コードが膨らんでいます（ただし、コメントは崩壊する可能性があります）。しかし、実際に他の人にドキュメントを送付しても、かなり参考になります。

Answer 2

これらのコメントには特別な理由があります。ドキュメントを生成したり、オートコンプリートに追加情報を追加したりするために使用できます。私は彼らが過度に冗長であり、ほとんどの状況では読みにくいことに同意しますが、あなたは外部に公開する予定のインターフェースに追加することをお勧めします。

コメントのオン/オフを切り替えるエディタの使用をお勧めします。

言語によっては、変数や関数のメタデータとしてコメントを保存することができますが、これは素晴らしい方法です。

Answer 3

個人的には、あなたが持っているものは少し外にあると思います。

"参照"リファレンスの目的は、解析後に生成されたヘルプドキュメントのトピック間の良好なリンクを提供することです。あなたのケースでは

、あなたのビジネス固有のライブラリは、言語の項目、すなわちを参照しています

<see langword="true"/> 

私は個人的にあなたのライブラリ内の他の関連するオブジェクトへのハイパーリンクは非常に便利な機能であると感じています。これにより、ヘルプをユーザーにとってより使いやすくすることができます。

言語要素へのハイパーリンクは、言語のヘルプそのものの内部にしか存在しないと感じるものです。サードパーティ製のライブラリの場合、これはどこにでもリンクを張ってメッセージを混乱させるだけです。これは良いリンクをあまり効果的にしません。

あなたのライブラリの関連クラスへのリンクを自由に使用することをお勧めします。私はベースライブラリクラスにハイパーリンクを追加することは避けていますが、何らかの理由で（特にまれに）特に便利な特定のインスタンスを除きます。 "true"と "IDisposable.Dispose"などにリンクすると、本当に多くの価値が追加されるわけではありません。

ユーザーが基本フレームワークを理解できるように信頼しますが、あなたのライブラリについて教えてください。

Answer 4

ctackeが述べたように、ハイパーリンクには非常に便利です。ただし、実際にドキュメントを出荷していない場合は、そのすべてのタグ付けにより、ドキュメントを読むことが事実上不可能になります。その場合、ドキュメンテーションは（開発者：内部）開発者のためのもので、読めない場合は時間を無駄にしています。

一般的に、私はタイプまたはメンバーへの最初の参照になりがちであり、残りはリンクされていません。コメントをきれいにして、意味のあるリンクを提供します。

Answer 5

Visual Studioを使って作業しているときは、WYSiWYGのコメントの読み取り/書き込み用にCR_Documentorプラグイン（無料ですが、here）を使用できます。 SandcastleやNDocのように生成されたヘルプのようですが、その場でレンダリングされます。 これは本当に便利で、生のxmlコメントはまったく気にする必要はありません。