XML コメントを使用してコードを文書化する
F# では、トリプル スラッシュ (///) コード コメントからドキュメントを生成できます。 XML コメントは、コード ファイル (.fs) またはシグネチャ (.fsi) ファイルの宣言の前に置くことができます。
XML ドキュメント のコメントは、ユーザー定義型またはメンバーの定義の上に追加された特別な種類のコメントです。 コンパイル時に XML ドキュメント ファイルを生成するためにコンパイラで処理できるため、これらは特別です。 コンパイラによって生成された XML ファイルを .NET アセンブリと共に配布して、IDE がツールヒントを使用して型またはメンバーに関する簡単な情報を表示できるようにします。 さらに、XML ファイルは、fsdocs などのツールを使用して実行して、API 参照 Web サイトを生成できます。
既定では、XML ドキュメントコメントはコンパイラによって無視されます。 これを変更するには、--warnon:3390設定します。 その後、コンパイラは XML の構文と、<param> タグと <paramref> タグで参照されるパラメーターを検証します。
コンパイル時に XML ファイルを生成するには、次のいずれかの操作を行います。
.fsprojプロジェクト ファイルの<PropertyGroup>セクションにGenerateDocumentationFile要素を追加すると、アセンブリと同じルート ファイル名を持つ XML ファイルがプロジェクト ディレクトリに生成されます。 例えば：<GenerateDocumentationFile>true</GenerateDocumentationFile>詳細については、「GenerateDocumentationFile プロパティの
を参照してください。 Visual Studio を使用してアプリケーションを開発している場合は、プロジェクトを右クリックし、[プロパティ]
選択します。 プロパティ ダイアログ ボックスで、 [ビルド] タブをクリックし、 [XML ドキュメント ファイル] をオンにします。 コンパイラがファイルを書き込む場所を変更することもできます。
XML ドキュメント コメントを記述するには、XML タグの有無に関する 2 つの方法があります。 どちらもトリプルスラッシュコメントを使用します。
XML タグのないコメント
/// コメントが <で始まらない場合、コメント テキスト全体が、直後に続くコードコンストラクトの概要ドキュメントとして取得されます。 各コンストラクトの簡単な概要のみを記述する場合は、このメソッドを使用します。
コメントはドキュメントの準備中に XML にエンコードされるため、<、>、& などの文字をエスケープする必要はありません。 サマリータグを明示的に指定しない場合は、パラメーター のタグや、タグを返す のタグなど、他のタグを指定しないでください。
次の例は、XML タグのない代替方法を示しています。 この例では、コメント内のテキスト全体が概要と見なされます。
/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string
XML タグを含むコメント
コメント本文が < で始まる場合 (通常は <summary>)、XML タグを使用して XML 形式のコメント本文として扱われます。 この 2 つ目の方法では、短い要約、追加の注釈、各パラメーターと型パラメーターとスローされる例外のドキュメント、戻り値の説明を個別に指定できます。
署名ファイル内の一般的な XML ドキュメント コメントを次に示します。
/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string
推奨タグ
XML タグを使用している場合は、次の表に、F# XML コード コメントで認識される外部タグについて説明します。
| タグ構文 | 説明 |
|---|---|
<summary> テキスト</summary> |
テキスト がプログラム要素の簡単な説明であることを指定します。 通常、説明は 1 つまたは 2 つの文です。 |
<remarks> テキスト</remarks> |
テキスト にプログラム要素に関する補足情報が含まれていることを指定します。 |
<param name=" 名前">説明</param> |
関数またはメソッド パラメーターの名前と説明を指定します。 |
<typeparam name=" 名前">説明</typeparam> |
型パラメーターの名前と説明を指定します。 |
<returns> テキスト</returns> |
テキスト が関数またはメソッドの戻り値を記述することを指定します。 |
<exception cref=" 型">説明</exception> |
生成できる例外の種類と、例外がスローされる状況を指定します。 |
<seealso cref="リファレンス"/> |
別の種類のドキュメントへの [参照] リンクを指定します。 参照 は、XML ドキュメント ファイルに表示される名前です。 ドキュメント ページの下部に通常表示されるリンクも参照してください。 |
次の表では、説明セクション内で使用するタグについて説明します。
| タグ構文 | 説明 |
|---|---|
<para> テキスト</para> |
テキストの段落を指定します。 これは、解説 タグ内のテキストを区切るために使用されます。 |
<code> テキスト</code> |
テキストが複数行のコードであることを指定します。 このタグは、ドキュメント ジェネレーターがコードに適したフォントでテキストを表示するために使用できます。 |
<paramref name=" 名前"/> |
同じドキュメント コメント内のパラメーターへの参照を指定します。 |
<typeparamref name=" 名前"/> |
同じドキュメント コメント内の型パラメーターへの参照を指定します。 |
<c> テキスト</c> |
テキスト がインラインコードであることを指定します。 このタグは、ドキュメント ジェネレーターがコードに適したフォントでテキストを表示するために使用できます。 |
<see cref=" 参照">テキスト</see> |
別のプログラム要素へのインライン リンクを指定します。 参照 は、XML ドキュメント ファイルに表示される名前です。 テキスト は、リンクに表示されるテキストです。 |
ユーザー定義タグ
上記のタグは、F# コンパイラと一般的な F# エディター ツールによって認識されるタグを表します。 ただし、ユーザーは自分のタグを自由に定義できます。
fsdoc などのツールは、namespacedoc
コンパイル時のチェック
--warnon:3390 が有効になっている場合、コンパイラは XML の構文と、<param> タグと <paramref> タグで参照されるパラメーターを検証します。
F# コンストラクトの文書化
モジュール、メンバー、共用体ケース、レコード フィールドなどの F# コンストラクトは、宣言の直前に /// コメントによって文書化されます。
必要に応じて、引数リストの前に /// コメントを付けることで、クラスの暗黙的なコンストラクターが文書化されます。 例えば：
/// This is the type
type SomeType
/// This is the implicit constructor
(a: int, b: int) =
/// This is the member
member _.Sum() = a + b
制限
C# およびその他の .NET 言語の XML ドキュメントの一部の機能は、F# ではサポートされていません。
F# では、クロス参照では、対応するシンボルの完全な XML シグネチャ (たとえば、
cref="T:System.Console") を使用する必要があります。cref="Console"などの単純な C# スタイルの相互参照は、完全な XML シグネチャには詳しく説明されておらず、これらの要素は F# コンパイラによってチェックされません。 一部のドキュメント ツールでは、後続の処理でこれらの相互参照を使用できる場合がありますが、完全な署名を使用する必要があります。<inheritdoc><include>タグは、F# コンパイラではサポートされていません。 使用されている場合はエラーは発生しませんが、生成されたドキュメントに影響を与えずに、生成されたドキュメント ファイルに単純にコピーされます。-warnon:3390が使用されている場合でも、F# コンパイラでは相互参照はチェックされません。タグ
<typeparam>および<typeparamref>で使用される名前は、--warnon:3390が使用されている場合でも、F# コンパイラによってチェックされません。--warnon:3390が使用されている場合でも、ドキュメントがない場合は警告は表示されません。
推奨 事項
コードの文書化は、さまざまな理由で推奨されます。 次に示すのは、ベスト プラクティス、一般的なユース ケース シナリオ、F# コードで XML ドキュメント タグを使用する場合に知っておくべきことです。
XML ドキュメントが有効な XML であることを確認するために、コードでオプション
--warnon:3390を有効にします。署名ファイルを追加して、長い XML ドキュメント コメントを実装から分離することを検討してください。
一貫性を確保するために、公開されているすべての型とそのメンバーを文書化する必要があります。 やらなければならないなら、すべてやり遂げる。
少なくとも、モジュール、型、およびそのメンバーには、プレーンな
///コメントまたは<summary>タグが必要です。 F# 編集ツールのオートコンプリート ツールヒント ウィンドウに表示されます。ドキュメントテキストは、完全な文を使用し、句点で終わる必要があります。
関連項目
.NET