XML ドキュメント (F#)

F# では、スラッシュ 3 個 (///) のコード コメントからドキュメントを生成できます。コード ファイル (.fs) またはシグネチャ (.fsi) ファイルでは、宣言の前に XML コメントを記述できます。

コメントからのドキュメント生成

F# では、他の .NET Framework 言語と同様に、コメントからのドキュメント生成がサポートされています。他の .NET Framework 言語と同様に、-doc コンパイラ オプションを使用すると、ドキュメントに変換できる情報が含まれた XML ファイルを生成できます。変換には、Sandcastle などのツールを使用します。他の .NET Framework 言語で記述されたアセンブリ用に設計されたツールを使用して生成したドキュメントは、通常、F# の構成要素のコンパイルされた形式に基づく API のビューを生成します。F# を明示的にサポートしているツールでない限り、これらのツールによって生成されたドキュメントは、F# での API のビューとは一致しません。

XML からドキュメントを生成する方法の詳細については、「XML ドキュメント コメント (C# プログラミング ガイド)」を参照してください。

推奨されるタグ

XML ドキュメントのコメントを記述するには、2 つの方法があります。第 1 の方法では、XML タグを使用しないで、トリプル スラッシュ コメント内にドキュメントを直接記述します。このようにすると、コメント テキスト全体が、直後にあるコード コンストラクターの概要ドキュメントとして解釈されます。各構成要素の概要のみを記述する場合は、この方法を使用します。もう 1 つの方法では、XML タグを使用して、より構造化されたドキュメントを記述します。2 番目の方法を使用すると、概要、補足説明、各パラメーターおよび型パラメーターとスローされた例外のドキュメント、および戻り値の説明を個別に指定できます。次の表では、F# の XML コード コメントで認識される XML タグについて説明します。

タグの構文	Description
<c>text</c>	text がコードであることを指定します。このタグは、コードに適したフォントでテキストを表示するためにドキュメント ジェネレーターで使用できます。
<summary>text</summary>	text がプログラム要素の簡単な説明であることを指定します。通常は、1 または 2 文で説明を記述します。
<remarks>text</remarks>	text がプログラム要素についての補足情報であることを指定します。
<param name="名前"> 説明</param>	関数またはメソッドのパラメーターの名前と説明を指定します。
<typeparam name="名前"> 説明 </typeparam>	型パラメーターの名前と説明を指定します。
<returns>text</returns>	text が関数またはメソッドの戻り値の説明であることを指定します。
<exception cref="型">説明</exception>	生成される可能性のある例外の型およびその例外がスローされる条件を指定します。
<see cref="参照">テキスト</see>	別のプログラム要素へのインライン リンクを指定します。reference は、XML ドキュメント ファイルで使用される名前です。text はリンクに表示されるテキストです。
<seealso cref="リファレンス"/>	別の種類のドキュメントに対する参照リンクを指定します。reference は、XML ドキュメント ファイルで使用される名前です。通常、参照リンクは、ドキュメント ページの下部に表示されます。
<para>text</para>	テキストの段落を指定します。remarks タグの内部のテキストの段落分けに使用します。

例

Description

シグネチャ ファイルでの標準的な 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

例

Description

次の例では、XML タグを使用しない方法を示します。この例では、コメント内のテキスト全体が概要と見なされます。summary タグを明示的に指定しない場合は、param や returns などの他のタグを指定できないことに注意してください。

コード

/// 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

参照

その他の技術情報

F# 言語リファレンス

コンパイラ オプション (F#)