23

APIドキュメントの生成に使用されるツールが部分クラスに対するXMLスタイルのコメントを持つことを処理する標準的な方法はありますか？基本的に、結果のヘルプドキュメントが壊れないように、部分的なクラス/メソッドにどのようにコメントする必要がありますか？この質問は、使用するツールによって異なる可能性があります。その場合、最も重要な2つのツールは次のとおりです。

  • XMLドキュメントを作成するためのVisualStudioの組み込みメソッド
  • マイクロソフトのサンドキャッスル

XMLドキュメントをファンキーに見せたくないのはすべてです

/// <summary>Some Foo class</summary>
public partial class Foo { ... }

/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }
4

1 に答える 1

20

ベストプラクティスは、部分的な定義の1つだけにXMLコメントを付けることです。1つのクラスのパブリックコメントを2つの場所に分割する必要はありません。（もちろん、通常のコメントは、各部分的な定義に含めるのが理にかなっています。）

Visual Studioが機能する方法は、一方の部分的な定義のコメントがもう一方の定義を上書きすることです。これを確認するには、XMLコメントが異なる同じクラスの2つの部分的な定義を作成してから、このタイプの変数を作成します。インテリセンスは、XMLコメントの1つだけを表示します。

これは、Sandcastleを含むVisualStudioによって生成されたXMLコメントファイルを使用するドキュメントツールの動作にもなります。

于 2011-05-12T23:52:17.953 に答える