XML コメントを含むコードの文書化

[アーティクル]
03/12/2024

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

XML 文書化コメントは、ユーザー定義型またはユーザー定義メンバーの定義の上に追加する特殊なコメントです。このコメントが特殊な理由は、コンパイル時にコンパイラで処理して、XML 文書化ファイルを生成できることです。コンパイラによって生成された XML ファイルは、.NET アセンブリと共に配布できます。これにより、IDE でツールヒントを使用して、型やメンバーに関する概要情報を表示できます。さらに、fsdocs のようなツールを使用して XML ファイルを実行し、API リファレンスの Web サイトを生成することができます。

XML ドキュメントコメントは、他のすべてのコメントと同様にコンパイラによって無視されます。ただし、コンパイル時にコメントの有効性と完全性を確認するために以下で説明するオプションが有効になっている場合は除きます。

コンパイル時に XML ファイルを生成するには、次のいずれかを実行します。

.fsproj プロジェクトファイルの <PropertyGroup> セクションに GenerateDocumentationFile 要素を追加することで、アセンブリと同じルートファイル名でプロジェクトディレクトリに XML ファイルを生成することができます。次に例を示します。
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
詳細については、「GenerateDocumentationFile プロパティ」を参照してください。
Visual Studio を使用してアプリケーションを開発する場合は、プロジェクトを右クリックして、 [プロパティ] を選択します。プロパティダイアログボックスで、 [ビルド] タブをクリックし、 [XML ドキュメントファイル] をオンにします。コンパイラがファイルを書き込む場所を変更することもできます。

XML ドキュメントコメントを記述するには、XML タグを使用する方法と使用しない方法の 2 つがあります。どちらも、トリプルスラッシュのコメントを使用します。

XML タグを使用しないコメント

/// コメントの最初が < でない場合、コメントのテキスト全体が、直後に続くコードコンストラクトの概要ドキュメントとして使用されます。各コンストラクトの概要のみを記述する場合は、この方法を使用してください。

コメントはドキュメントの準備中に XML にエンコードされるため、<>& などの文字をエスケープする必要はありません。 summary タグを明示的に指定しない場合は、param や returns タグなど、他のタグを指定しないでください。

次の例は、XML タグを使用しない別の方法を示しています。この例では、コメント内のテキスト全体が概要と見なされます。

/// 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 タグを使用したコメント

コメントの本文が < (通常は <summary>) で始まる場合、XML タグを使用した XML 形式のコメント本文として扱われます。この 2 つ目の方法を使用すると、簡単な概要、追加の注釈、各パラメーター、型パラメーター、スローされる例外についてのドキュメント、戻り値の説明に関して、個別に注意事項を指定できます。

次に、シグネチャファイル内の一般的な 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

推奨タグ

XML タグを使用する場合、F# の XML コードコメントで認識される外部タグについて次の表で説明します。

タグ構文	説明
`<summary>`*text*`</summary>`	テキストがプログラム要素の簡単な説明であることを指定します。説明は、通常、1 つまたは 2 つの文です。
`<remarks>`*text*`</remarks>`	テキストにプログラム要素に関する補足情報が含まれていることを指定します。
`<param name="`名前`">`説明`</param>`	関数またはメソッドのパラメーターの名前と説明を指定します。
`<typeparam name="`名前`">`説明`</typeparam>`	型パラメーターの名前と説明を指定します。
`<returns>`*text*`</returns>`	テキストに関数またはメソッドの戻り値が記述されることを指定します。
`<exception cref="`型`">`説明`</exception>`	生成できる例外の型と、その例外がスローされる状況を指定します。
`<seealso cref="`*参照先*`"/>`	別の型のドキュメントへの [関連項目] リンクを指定します。参照先は、XML ドキュメントファイルに表示される名前です。通常、ドキュメントページの下部には [関連項目] リンクが表示されます。

次の表では、説明セクション内で使用するタグについて説明します。

タグ構文	説明
`<para>`*text*`</para>`	テキストの段落を指定します。これは、remarks タグ内のテキストを区切るために使用されます。
`<code>`*text*`</code>`	テキストが複数行のコードであることを指定します。このタグは、ドキュメントジェネレーターがコードに適したフォントでテキストを表示するために使用できます。
`<paramref name="`*name*`"/>`	同じドキュメントコメント内のパラメーターへの参照を指定します。
`<typeparamref name="`*name*`"/>`	同じドキュメントコメント内の型パラメーターへの参照を指定します。
`<c>`*text*`</c>`	テキストがインラインコードであることを指定します。このタグは、ドキュメントジェネレーターがコードに適したフォントでテキストを表示するために使用できます。
`<see cref="`*参照先`">`テキスト*`</see>`	別のプログラム要素へのインラインリンクを指定します。参照先は、XML ドキュメントファイルに表示される名前です。テキストは、リンクに表示されるテキストです。

ユーザー定義タグ

これまでのタグは、F# コンパイラおよび一般的な F# エディターツールによって認識されるものを表しています。ただし、ユーザー独自のタグも自由に定義できます。 fsdocs などのツールを使用すると、<namespacedoc> などの追加のタグもサポートされます。カスタムまたは社内ドキュメント生成ツールを標準タグと共に使用して、HTML から PDF への複数の出力形式をサポートできます。

コンパイル時のチェック

--warnon:3390 が有効になっている場合、コンパイラでは、XML の構文と、<param> および <paramref> タグで参照されるパラメーターを検証します。

F# コンストラクトのドキュメント化

モジュール、メンバー、共用体ケース、レコードフィールドなどの F# コンストラクトは、宣言の直前に /// コメントによってドキュメント化されます。必要に応じて、引数リストの前に /// コメントを付けることで、クラスの暗黙的なコンストラクターがドキュメント化されます。次に例を示します。

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

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

制限事項

C# やその他の .NET 言語の XML ドキュメントに関する一部の機能は、F# ではサポートされていません。

F# の場合、相互参照では、該当するシンボル (たとえば cref="T:System.Console") の完全な XML シグネチャを使用する必要があります。 cref="Console" などの単純な C# スタイルの相互参照は、完全な XML シグネチャ向けに詳細に作成されておらず、これらの要素は F# コンパイラによってチェックされません。一部のドキュメントツールでは、後続の処理でこれらの相互参照を使用できますが、完全なシグネチャを使用する必要があります。
タグ <include>、<inheritdoc> は、F# コンパイラではサポートされていません。これらが使用されている場合、エラーは発生しませんが、生成されたドキュメントに影響を与えずに、単に生成されたドキュメントファイルにコピーされます。
-warnon:3390 が使用されている場合でも、相互参照は F# コンパイラによってチェックされません。
--warnon:3390 が使用されている場合でも、タグ <typeparam> と <typeparamref> で使用される名前は、F# コンパイラによってチェックされません。
--warnon:3390 が使用されている場合でも、ドキュメントが見つからないときは、警告は与えられません。

推奨事項

コードを文書化することをお勧めするのには、さまざまな理由があります。いくつかのベストプラクティス、一般的なユースケースのシナリオ、XML 文書化タグを F# コードで使用するときに知っておく必要があることを以下に示します。

コードでオプション --warnon:3390 を有効にすると、XML ドキュメントが有効な XML であることを保証できます。
シグネチャファイルを追加して、長い XML ドキュメントコメントを実装から分離することを検討してください。
整合性を保つため、一般に公開されているすべての型とそのメンバーを文書化する必要があります。必要な文書化はすべて実行してください。
モジュール、型、およびそれらのメンバーには、少なくとも普通の /// コメントまたは <summary> タグが必要です。これは、F# 編集ツールのオートコンプリートツールヒントウィンドウに表示されます。
文書化のテキストは、句点で終わる完全な文を使用して作成する必要があります。