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