XML ドキュメントXML Documentation

でF#は、トリプルスラッシュ (///) コードコメントからドキュメントを生成できます。You can produce documentation from triple-slash (///) code comments in F#. XML コメントは、コードファイル (fs) ファイルまたは署名 (fsi.exe) ファイルの宣言の前に記述できます。XML comments can precede declarations in code files (.fs) or signature (.fsi) files.

コメントからドキュメントを生成するGenerating Documentation from Comments

コメントからドキュメントF#を生成するためののサポートは、他の .NET Framework 言語のドキュメントと同じです。The support in F# for generating documentation from comments is the same as that in other .NET Framework languages. 他の .NET Framework 言語と同様に、 -doc コンパイラオプションを使用すると、 DocfxSandcastleなどのツールを使用してドキュメントに変換できる情報を含む XML ファイルを生成できます。As in other .NET Framework languages, the -doc compiler option enables you to produce an XML file that contains information that you can convert into documentation by using a tool such as DocFX or Sandcastle. 他の .NET Framework 言語で記述されたアセンブリで使用できるように設計されたツールを使用して生成されたドキュメントでは、一般に、 F#コンパイル済みの構造の形式に基づく api のビューが生成されます。The documentation generated by using tools that are designed for use with assemblies that are written in other .NET Framework languages generally produce a view of the APIs that is based on the compiled form of F# constructs. ツールで特にF#をサポートしていない限り、これらのF#ツールで生成されたドキュメントは API のビューと一致しません。Unless tools specifically support F#, documentation generated by these tools does not match the F# view of an API.

Xml からドキュメントを生成する方法の詳細については、「 xml#ドキュメントコメント) (C プログラミングガイド」を参照してください。For more information about how to generate documentation from XML, see XML Documentation Comments (C# Programming Guide).

XML ドキュメントコメントを記述するには、2つの方法があります。There are two ways to write XML documentation comments. 1つは、XML タグを使用せずに、ドキュメントを三重スラッシュのコメントに直接記述することです。One is to just write the documentation directly in a triple-slash comment, without using XML tags. これを行うと、コメントテキスト全体が、すぐ後に続くコードコンストラクターの概要ドキュメントとして取得されます。If you do this, the entire comment text is taken as the summary documentation for the code construct that immediately follows. 各コンストラクトの概要のみを記述する場合は、このメソッドを使用します。Use this method when you want to write only a brief summary for each construct. もう1つの方法は、XML タグを使用して、より構造化されたドキュメントを提供することです。The other method is to use XML tags to provide more structured documentation. 2番目の方法では、簡単な概要、追加の解説、各パラメーターのドキュメント、スローされる例外の種類、および戻り値の説明について、個別のメモを指定できます。The second method enables you to specify separate notes for a short summary, additional remarks, documentation for each parameter and type parameter and exceptions thrown, and a description of the return value. 次の表では、xml コードコメントでF#認識される xml タグについて説明します。The following table describes XML tags that are recognized in F# XML code comments.

タグ構文Tag syntax 説明Description
<c> text </c><c>text</c> テキストがコードであることを指定します。Specifies that text is code. このタグは、ドキュメントジェネレーターがコードに適したフォントでテキストを表示するために使用できます。This tag can be used by documentation generators to display text in a font that is appropriate for code.
<概要> テキスト </概要><summary>text</summary> テキストがプログラム要素の簡単な説明であることを指定します。Specifies that text is a brief description of the program element. 説明は、通常、1つまたは2つの文です。The description is usually one or two sentences.
<解説> テキスト </解説><remarks>text</remarks> Textに program 要素に関する補足情報が含まれていることを指定します。Specifies that text contains supplementary information about the program element.
<param name = " name "> description </param><param name="name">description</param> 関数またはメソッドのパラメーターの名前と説明を指定します。Specifies the name and description for a function or method parameter.
<typeparam name = " name "> description </typeparam><typeparam name="name">description</typeparam> 型パラメーターの名前と説明を指定します。Specifies the name and description for a type parameter.
<は> テキスト </を返し><returns>text</returns> 関数またはメソッドの戻り値をテキストに記述するように指定します。Specifies that text describes the return value of a function or method.
<exception cref=" type "> description </exception><exception cref="type">description</exception> 生成できる例外の種類と、その例外がスローされる状況を指定します。Specifies the type of exception that can be generated and the circumstances under which it is thrown.
<「cref = " 参照 "> テキスト <を参照してください><see cref="reference">text</see> 別のプログラム要素へのインラインリンクを指定します。Specifies an inline link to another program element. 参照は、XML ドキュメントファイルに表示される名前です。The reference is the name as it appears in the XML documentation file. テキストは、リンクに表示されるテキストです。The text is the text shown in the link.
<seealso cref=" reference "/><seealso cref="reference"/> 別の種類のドキュメントへのリンクも参照してください。Specifies a See Also link to the documentation for another type. 参照は、XML ドキュメントファイルに表示される名前です。The reference is the name as it appears in the XML documentation file. ドキュメントページの下部には、通常、リンクも表示されます。See Also links usually appear at the bottom of a documentation page.
<段落> テキスト </段落><para>text</para> テキストの段落を指定します。Specifies a paragraph of text. これは、コメントタグ内のテキストを区切るために使用されます。This is used to separate text inside the remarks tag.

使用例Example

説明Description

シグネチャファイル内の一般的な XML ドキュメントコメントを次に示します。The following is a typical XML documentation comment in a signature file.

コードCode

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

使用例Example

説明Description

次の例は、XML タグのない代替メソッドを示しています。The following example shows the alternative method, without XML tags. この例では、コメント内のテキスト全体が概要と見なされます。In this example, the entire text in the comment is considered a summary. 概要タグを明示的に指定しない場合は、 paramや returns タグなど、他のタグを指定しないでください。Note that if you do not specify a summary tag explicitly, you should not specify other tags, such as param or returns tags.

コードCode

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

関連項目See also