次の方法で共有


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#)