XML コメントを含むコードの文書化Document your code with XML comments

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.

XML 文書化コメントは、ユーザー定義型またはユーザー定義メンバーの定義の上に追加する特殊なコメントです。XML documentation comments are a special kind of comment, added above the definition of any user-defined type or member. このコメントが特殊な理由は、コンパイル時にコンパイラで処理して、XML 文書化ファイルを生成できることです。They are special because they can be processed by the compiler to generate an XML documentation file at compile time. コンパイラによって生成された XML ファイルは、.NET アセンブリと共に配布できます。これにより、Ide では、ツールヒントを使用して型またはメンバーに関する簡単な情報を表示できます。The compiler-generated XML file can be distributed alongside your .NET assembly so that IDEs can use tooltips to show quick information about types or members. また、XML ファイルは、 fsdocs などのツールを使用して実行し、API 参照 web サイトを生成することもできます。Additionally, the XML file can be run through tools like fsdocs to generate API reference websites.

他のすべてのコメントと同様に、XML ドキュメントのコメントはコンパイラによって無視されます。ただし、以下で説明するオプションを使用して、コンパイル時にコメントの有効性と完全性をチェックすることはできません。XML documentation comments, like all other comments, are ignored by the compiler, unless the options described below are enabled to check the validity and completeness of comments at compile-time.

コンパイル時に XML ファイルを生成するには、次のいずれかを実行します。You can generate the XML file at compile time by doing one of the following:

  • GenerateDocumentationFileプロジェクトファイルのセクションに要素を追加できます <PropertyGroup> .fsproj 。これにより、アセンブリと同じルートファイル名を持つ XML ファイルがプロジェクトディレクトリに生成されます。You can add a GenerateDocumentationFile element to the <PropertyGroup> section of your .fsproj project file, which generates an XML file in the project directory with the same root filename as the assembly. 次に例を示します。For example:

    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    
  • Visual Studio を使用してアプリケーションを開発する場合は、プロジェクトを右クリックして、 [プロパティ] を選択します。If you are developing an application using Visual Studio, right-click on the project and select Properties. プロパティ ダイアログ ボックスで、 [ビルド] タブをクリックし、 [XML ドキュメント ファイル] をオンにします。In the properties dialog, select the Build tab, and check XML documentation file. コンパイラがファイルを書き込む場所を変更することもできます。You can also change the location to which the compiler writes the file.

XML ドキュメントコメントを記述するには、XML タグの有無にかかわらず、2つの方法があります。There are two ways to write XML documentation comments: with and without XML tags. どちらも、3つのスラッシュを使用します。Both use triple-slash comments.

XML タグのないコメントComments without XML tags

コメントが /// で始まらない場合、 < コメントテキスト全体が、直後に続くコードコンストラクターの概要ドキュメントとして取得されます。If a /// comment does not start with a < then 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.

コメントはドキュメントの準備中に XML にエンコードされます。そのため、などの文字を < > & エスケープする必要はありません。The comment is encoded to XML during documentation preparation, so characters such as <, > and & need not be escaped. 概要タグを明示的に指定しない場合は、 param や returns タグなど、他の タグを 指定しないでください。If you don't specify a summary tag explicitly, you should not specify other tags, such as param or returns tags.

次の例は、XML タグのない代替メソッドを示しています。The following example shows the alternative method, without XML tags. この例では、コメント内のテキスト全体が概要と見なされます。In this example, the entire text in the comment is considered a summary.

/// 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 タグの付いたコメントComments with XML tags

コメントの本文が (通常は) で始まる場合、 < <summary> xml タグを使用する xml 形式のコメント本文として扱われます。If a comment body begins with < (normally <summary>) then it is treated as an XML formatted comment body using XML tags. この2番目の方法では、簡単な概要、追加の解説、各パラメーターのドキュメント、スローされる例外の種類、および戻り値の説明を個別に指定できます。This second 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 ドキュメントコメントを示します。The following is a typical XML documentation comment in a signature file:

/// <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 コードコメントで認識される外側のタグについて、次の表で説明します。If you are using XML tags, the following table describes the outer tags recognized in F# XML code comments.

タグ構文Tag syntax [説明]Description
<summary>本文</summary><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>本文</remarks><remarks>text</remarks> Textに program 要素に関する補足情報が含まれていることを指定します。Specifies that text contains supplementary information about the program element.
<param name="名前 ">説明</param><param name="name">description</param> 関数またはメソッドのパラメーターの名前と説明を指定します。Specifies the name and description for a function or method parameter.
<typeparam name="名前 ">説明</typeparam><typeparam name="name">description</typeparam> 型パラメーターの名前と説明を指定します。Specifies the name and description for a type parameter.
<returns>本文</returns><returns>text</returns> 関数またはメソッドの戻り値を テキスト に記述するように指定します。Specifies that text describes the return value of a function or method.
<exception cref=" ">説明</exception><exception cref="type">description</exception> 生成できる例外の種類と、その例外がスローされる状況を指定します。Specifies the type of exception that can be generated and the circumstances under which it is thrown.
<seealso cref=""/><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.

次の表では、説明セクション内で使用するタグについて説明します。The following table describes the tags for use inside description sections:

タグ構文Tag syntax [説明]Description
<para>本文</para><para>text</para> テキストの段落を指定します。Specifies a paragraph of text. これは、 コメント タグ内のテキストを区切るために使用されます。This is used to separate text inside the remarks tag.
<code>本文</code><code>text</code> テキストが複数行のコードであることを指定します。Specifies that text is multiple lines of code. このタグは、ドキュメントジェネレーターがコードに適したフォントでテキストを表示するために使用できます。This tag can be used by documentation generators to display text in a font that is appropriate for code.
<paramref name="指定"/><paramref name="name"/> 同じドキュメントコメント内のパラメーターへの参照を指定します。Specifies a reference to a parameter in the same documentation comment.
<typeparamref name="指定"/><typeparamref name="name"/> 同じドキュメントコメント内の型パラメーターへの参照を指定します。Specifies a reference to a type parameter in the same documentation comment.
<c>本文</c><c>text</c> テキストがインラインコードであることを指定します。Specifies that text is inline code. このタグは、ドキュメントジェネレーターがコードに適したフォントでテキストを表示するために使用できます。This tag can be used by documentation generators to display text in a font that is appropriate for code.
<see cref="参照 ">テキスト</see><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.

ユーザー定義タグUser-defined tags

前のタグは、F # コンパイラおよび一般的な F # エディターツールによって認識されるタグを表します。The previous tags represent those that are recognized by the F# compiler and typical F# editor tooling. ただし、ユーザー独自のタグも自由に定義できます。However, a user is free to define their own tags. Fsdocs などのツールでは、のような余分なタグがサポート対象と <namespacedoc> なります。Tools like fsdocs bring support for extra tags like <namespacedoc>. カスタムまたは社内ドキュメント生成ツールを標準タグと共に使用して、HTML から PDF への複数の出力形式をサポートできます。Custom or in-house documentation generation tools can also be used with the standard tags and multiple output formats from HTML to PDF can be supported.

コンパイル時のチェックCompile-time checking

が有効になっている場合 --warnon:3390 、コンパイラは、XML の構文と、タグとタグで参照されるパラメーターを検証し <param> <paramref> ます。When --warnon:3390 is enabled, the compiler verifies the syntax of the XML and the parameters referred to in <param> and <paramref> tags.

F # コンストラクトの文書化Documenting F# Constructs

モジュール、メンバー、共用体ケース、レコードフィールドなどの F # コンストラクトは、宣言の直前にコメントによって文書化され /// ます。F# constructs such as modules, members, union cases and record fields are documented by a /// comment immediately prior to their declaration. 必要に応じて、 /// 引数リストの前にコメントを付けることによって、クラスの暗黙的なコンストラクターを記述します。If needed, implicit constructors of classes are documented by giving a /// comment prior to the argument list. 次に例を示します。For example:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

制限事項Limitations

C# およびその他の .NET 言語の XML ドキュメントの一部の機能は、c# ではサポートされていません。Some features of XML documentation in C# and other .NET languages are not supported in C#.

  • F # では、相互参照では、対応するシンボルの完全な XML シグネチャ (たとえば) を使用する必要があり cref="T:System.Console" ます。In F#, cross-references must use the full XML signature of the corresponding symbol, for example cref="T:System.Console". などの単純な C# スタイルの相互参照 cref="Console" は、完全な XML シグネチャには対応していません。これらの要素は、F # コンパイラによってチェックされません。Simple C#-style cross-references such as cref="Console" are not elaborated to full XML signatures and these elements are not checked by the F# compiler. 一部のドキュメントツールでは、後続の処理でこれらの相互参照を使用できますが、完全なシグネチャを使用する必要があります。Some documentation tooling may allow the use of these these cross-references by subsequent processing, but the full signatures should be used.

  • タグは <include><inheritdoc> F # コンパイラではサポートされていません。The tags <include>, <inheritdoc> are not supported by the F# compiler. これらが使用されている場合、エラーは発生しませんが、生成されたドキュメントに影響を与えることなく、単に生成されたドキュメントファイルにコピーされます。No error is given if they are used, but they are simply copied to the generated documentation file without otherwise affecting the documentation generated.

  • が使用されている場合でも、相互参照は F # コンパイラによってチェックされません -warnon:3390Cross-references are not checked by the F# compiler, even when -warnon:3390 is used.

  • タグとで使用される名前は、 <typeparam> が使用されている <typeparamref> 場合でも、F # コンパイラによってチェックされません --warnon:3390The names used in the tags <typeparam> and <typeparamref> are not checked by the F# compiler, even when --warnon:3390 is used.

  • が使用されている場合でも、ドキュメントが見つからない場合、警告は与えられません --warnon:3390No warnings are given if documentation is missing, even when --warnon:3390 is used.

推奨事項Recommendations

コードを文書化することをお勧めするのには、さまざまな理由があります。Documenting code is recommended for many reasons. ここでは、F # コードで XML ドキュメントタグを使用するときに理解しておく必要があるベストプラクティス、一般的なユースケースシナリオ、および重要事項について説明します。What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your F# code.

  • --warnon:3390Xml ドキュメントが有効な xml であることを確認するために、コードでオプションを有効にします。Enable the option --warnon:3390 in your code to help ensure your XML documentation is valid XML.

  • 実装から長い XML ドキュメントコメントを分離するために、署名ファイルを追加することを検討してください。Consider adding signature files to separate long XML documentation comments from your implementation.

  • 整合性を保つため、一般に公開されているすべての型とそのメンバーを文書化する必要があります。For the sake of consistency, all publicly visible types and their members should be documented. 必要な文書化はすべて実行してください。If you must do it, do it all.

  • 最小限のモジュール、型、およびそれらのメンバーは、通常の /// コメントまたはタグを持つ必要があり <summary> ます。At a bare minimum, modules, types and their members should have a plain /// comment or <summary> tag. これは、F # 編集ツールのオートコンプリートツールヒントウィンドウに表示されます。This will show in an autocompletion tooltip window in F# editing tools.

  • 文書化のテキストは、句点で終わる完全な文を使用して作成する必要があります。Documentation text should be written using complete sentences ending with full stops.

関連項目See also