csharp-docs

C# ドキュメントのベストプラクティス

• パブリックメンバーは XML コメントで文書化する必要があります。
• 内部メンバーについても、特に複雑であったり自己説明的でない場合には、文書化することが推奨されます。

すべての API に関するガイダンス

• <summary> を使用して、型またはメンバーが何を行うかを簡潔に 1 文で説明します。概要は現在形の三人称の動詞で始めます。
• <remarks> を使用して、実装の詳細、使用上の注意、その他の関連するコンテキストなどの補足情報を記述します。
• <see langword> を null、true、false、int、bool などの言語固有のキーワードに使用します。
• <c> をインラインコードスニペットに使用します。
• <example> をメンバーの使用方法の例に使用します。
  • コードブロックには <code> を使用します。<code> タグは <example> タグ内に配置する必要があります。コード例の言語は language 属性を使用して追加します。たとえば、<code language="csharp"> のようにします。
• <see cref> を使用して、他の型またはメンバーをインライン (文中) で参照します。
• <seealso> を使用して、オンラインドキュメントの「関連項目」セクションで、他の型またはメンバーへの単独の (文中ではない) 参照を行います。
• <inheritdoc/> を使用して、基底クラスまたはインターフェイスからドキュメントを継承します。
  • 大きな動作の変更がない場合を除きます。その場合は、相違点を文書化する必要があります。

メソッド

• <param> を使用してメソッドのパラメーターを説明します。
  • 説明は、データ型を指定しない名詞句にする必要があります。
  • 導入の冠詞で始めます。
  • パラメーターがフラグ列挙型の場合、説明は「...を指定する列挙値のビット単位の組み合わせ。」で始めます。
  • パラメーターが非フラグ列挙型の場合、説明は「...を指定する列挙値の 1 つ。」で始めます。
  • パラメーターが Boolean の場合、文言は「... の場合は <see langword="true" />、それ以外の場合は <see langword="false" />。」の形式にする必要があります。
  • パラメーターが "out" パラメーターの場合、文言は「このメソッドから制御が戻るときに、... を格納します。このパラメーターは初期化されていないものとして扱われます。」の形式にする必要があります。
• <paramref> を使用して、ドキュメント内でパラメーター名を参照します。
• <typeparam> を使用して、ジェネリック型またはジェネリックメソッドの型パラメーターを説明します。
• <typeparamref> を使用して、ドキュメント内で型パラメーターを参照します。
• <returns> を使用して、メソッドが何を返すかを説明します。
  • 説明は、データ型を指定しない名詞句にする必要があります。
  • 導入の冠詞で始めます。
  • 戻り値の型が Boolean の場合、文言は「... の場合は <see langword="true" />、それ以外の場合は <see langword="false" />。」の形式にする必要があります。

コンストラクター

• 概要の文言は「 クラス [または構造体] の新しいインスタンスを初期化します。」にする必要があります。

プロパティ

• <summary> は次のように始める必要があります。
  • 読み書き可能なプロパティの場合は「...を取得または設定します。」
  • 読み取り専用プロパティの場合は「...を取得します。」
  • Boolean 値を返すプロパティの場合は「...かどうかを示す値 [を取得または設定します]。」
• <value> を使用してプロパティの値を説明します。
  • 説明は、データ型を指定しない名詞句にする必要があります。
  • プロパティに既定値がある場合は、別の文で追加します。たとえば、「既定値は <see langword="false" /> です。」のようにします。
  • 値の型が Boolean の場合、文言は「... の場合は <see langword="true" />、それ以外の場合は <see langword="false" />。既定値は ... です。」の形式にする必要があります。

例外

• <exception cref> を使用して、コンストラクター、プロパティ、インデクサー、メソッド、演算子、およびイベントによってスローされる例外を文書化します。
• メンバーによって直接スローされるすべての例外を文書化します。
• 入れ子になったメンバーによってスローされる例外については、ユーザーが最も遭遇する可能性が高い例外のみを文書化します。
• 例外の説明では、それがスローされる条件を説明します。
  • 文の冒頭の「... の場合にスローされます。」や「... の場合」は省略します。条件を直接記述するだけにします。たとえば、「Message Queuing API にアクセスしたときにエラーが発生しました。」のようにします。