XMLコメントにはどのような情報がありますか？

Question

メソッドを書き、コメントしたいときは、同じ情報をサマリータグに書きます。

例：

/// <summary> 
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary> 
/// <param name="id">customer id</param> 
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns> 
private Customer GetCustomerById(string id) 
{ 
    ... 
} 

最後に、これは本当に便利？どのような情報が提供され、どのタグでそれらを提供するのですか？

Answer 1

DRY（自分自身を繰り返さないでください）を検討してください。 paramエントリはパラメータを記述し、returnsエントリは何が返されるかを記述します。要約では、メソッドの概要を示し、他のエントリからの情報は繰り返さないようにしてください。

ドキュメントに記載されていないものは、実際のドキュメントです。 「文字列id」はIDを持つ文字列です。つまり、それは自己文書化です。しかし、どうすればこのメソッドを呼び出すことができますか？有効なユーザーIDは何ですか？ nullまたは空の文字列を渡すとどうなりますか？あなたは、パラメータの詳細のこれらの並べ替えを複製、私のアドイン（Atomineer Pro Documentation）のようなツールを使用している場合

/// <summary> Gets information on a customer </summary> 
/// 
/// <param name='id'> A customer identifier in the form of a GUID string. 
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}". 
/// Braces around the GUID are optional. 
/// This parameter must be a valid Guid. </param> 
/// 
/// <returns> A Customer record describing the given customer, or 
/// null if the Customer is not found</returns> 

：など

ここで物事がためのもので、どのようにメソッドを使用するもののマニュアルが含まれて仮想的な例ですクラスの周りは自明なので、メソッドをうまく文書化するのに時間を費やす必要はありません。

Answer 2

別の質問への答えはまた、あなたにお答えします：

は本当に有用な文書を提供しますか？

あなたが必要としているものを提供し、必要なものを提供します。この情報は、Visual StudioのコードコンシューマにIntelliSenseツールチップとして表示されます（.NETクラスおよびメンバのように表示されます）。

Answer 3

ライブラリを開発する場合、Xmlのドキュメントは非常に便利です。これらのxmlコメントに対してヘルプファイルを自動的に生成することができます。ヘルプファイルの生成の詳細については、thisを参照してください。 Xmlドキュメントタグの詳細については、MSDNをチェックしてください。

Answer 4

場合によっては、メソッド名またはプロパティ名が自明ですが、必ずしもそうであるとは限りません。あなたの事例でのイベント。提供されたIDが存在しない場合に起こることについての情報を提供する必要があります。あなたのメソッドは例外をスローしますか（もしそうなら、それはどんな例外になるでしょうか）、あるいは単にnullを返すか、一般的なCustomer.Emptyの値を返すでしょうか？場合によっては、コードサンプルを提供することもできます。

いずれにしても、いずれにしてもコードのドキュメントを提供することは常に良い方法です。

Answer 5

多くの場合、私はリターン要素を完全に切り捨てることをお勧めします。あなたの例は、これの素晴らしい例であるようです。ありがたいことに、VStudioはこれを警告付きの悪いコメントとしてマークしません。私がこれを行う理由は、80％以上のケースでは、私の文書は基本的に戻り値の型がどれほどのものか、関数の名前があまりにもはっきりとしているので、無駄な時間とエネルギーを無駄にするからです。これを含めると、DRYの違反につながることがよくあります。

あなたの例はこれの完璧な例です。

Customer GetCustomerById(string id) 

これがint idの場合、この関数はコメントを必要としない場合もあります。文字列では、それほど明確ではなく、明確化を使用するかもしれません。しかしどちらの場合でも、戻り値の型についてXMLコメントを提供するのは浪費のようです。これは主観的な質問であることを覚えておいてください。補完のために戻り値の型コメントを常に含むようにする人もいるかもしれません。私はVStudioの警告システムから始めて、それが必要ではないとうれしいです。