XML コメントを使用してコードを文書化する

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

XML ドキュメント のコメントは、ユーザー定義型またはメンバーの定義の上に追加された特別な種類のコメントです。 コンパイル時に XML ドキュメント ファイルを生成するためにコンパイラで処理できるため、これらは特別です。 コンパイラによって生成された XML ファイルを .NET アセンブリと共に配布して、IDE がツールヒントを使用して型またはメンバーに関する簡単な情報を表示できるようにします。 さらに、XML ファイルは、fsdocs などのツールを使用して実行して、API 参照 Web サイトを生成できます。

既定では、XML ドキュメントコメントはコンパイラによって無視されます。 これを変更するには、--warnon:3390設定します。 その後、コンパイラは XML の構文と、<param> タグと <paramref> タグで参照されるパラメーターを検証します。

プロジェクト ファイルでこの警告を有効にするには、 <WarnOn> 要素を <PropertyGroup> セクションに追加します。

<WarnOn>3390</WarnOn>

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

• GenerateDocumentationFile プロジェクト ファイルの <PropertyGroup> セクションに .fsproj 要素を追加すると、アセンブリと同じルート ファイル名を持つ XML ファイルがプロジェクト ディレクトリに生成されます。 例えば：

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

  詳細については、「GenerateDocumentationFile プロパティのを参照してください。

• Visual Studio を使用してアプリケーションを開発している場合は、プロジェクトを右クリックし、[プロパティ]選択します。 プロパティ ダイアログ ボックスで、 [ビルド] タブをクリックし、 [XML ドキュメント ファイル] をオンにします。 コンパイラがファイルを書き込む場所を変更することもできます。

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

XML タグのないコメント

/// コメントが <で始まらない場合、コメント テキスト全体が、直後に続くコードコンストラクトの概要ドキュメントとして取得されます。 各コンストラクトの簡単な概要のみを記述する場合は、このメソッドを使用します。

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

次の例は、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 コード コメントで認識される外部タグについて説明します。

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

ユーザー定義タグ

上記のタグは、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

ドキュメントの再利用と継承

共有されたコメントを 1 回保持するには、ソースの横にある shared.xml に配置します。

<docs>
  <tracking>
    <remarks>An unrecognized tracking identifier has status Unknown.</remarks>
  </tracking>
</docs>

どちらのメンバーも、同じ XPath 式を持つ要素を選択します。

/// <summary>Find the latest status of a shipment.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let status trackingId =
    if trackingId = "SHP-1042" then "Dispatched" else "Unknown"

/// <summary>Find the latest statuses of several shipments.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let statuses trackingIds =
    trackingIds |> List.map (fun id -> id, status id)

GenerateDocumentationFileを有効にするか、--doc:Tracking.xml渡します。 F# 11 以降では、出力されるエントリには、タグだけでなく、選択した注釈とローカルサマリーが含まれます。

サンプル プロジェクトでは、XML をコンパイル入力として追跡するため、トリガーの再生成が編集されます。 言語バージョンのオプトインは必要ありません。 ライブ クイック ヒントではなく、生成された XML の展開が含まれます。

解決策とエラーを含める

相対ファイル名は、最初にソース ファイルのディレクトリに対して解決され、次にコンパイラの作業ディレクトリに対して解決されます。 入れ子になったインクルードは、含まれている XML ファイルに対する相対解決を含みます。 テキストノードや属性ノードではなく、/docs/tracking/*などの要素を選択します。

不足しているファイル、形式が正しくない XML、無効な XPath、およびサイクルによって診断が生成されます。 一致しない有効な XPath はタグを保持し、警告なしでコメントを追加します。 DTD 処理と外部 XML 解決が無効になっています。foreign-namespace include 要素は通常のコンテンツのままです。 XPath 構文については、 <include> リファレンスを参照 してください。

ツールで継承されたドキュメント

基本メンバーの説明を各オーバーライドにコピーしないようにするには、 <inheritdoc/>を使用します。

[<AbstractClass>]
type TrackingBase() =
    /// <summary>Find the latest status of a shipment.</summary>
    abstract Status: trackingId: string -> string

type TrackingService() =
    inherit TrackingBase()
    /// <inheritdoc/>
    override _.Status trackingId = status trackingId

F# 11 ツールと FSharp.Compiler.Service は、 TrackingService.Statusの継承された説明を公開します。 コンパイラは、ダウンストリーム ツールが解釈するために出力された XML に <inheritdoc/> を残します。Core のみを更新しても、エディターのリゾルバーは更新されません。

<summary>内に入れ子になったタグではなく、最上位の<inheritdoc/>を使用します。 明示的な cref、コンストラクター、言語間またはアセンブリ間のケースは、ドキュメント コンシューマーによって異なります。 完全な XML ドキュメント識別子を使用し、ターゲット ツールを確認します。 <inheritdoc>リファレンスを参照してください。

制限

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

• F# では、クロス参照では、対応するシンボルの完全な XML シグネチャ (たとえば、cref="T:System.Console") を使用する必要があります。 cref="Console" などの単純な C# スタイルの相互参照は、完全な XML シグネチャには詳しく説明されておらず、これらの要素は F# コンパイラによってチェックされません。 一部のドキュメント ツールでは、後続の処理でこれらの相互参照を使用できる場合がありますが、完全な署名を使用する必要があります。

• F# 11 より前では、コンパイラは <include> を展開せずにコピーします。 <inheritdoc> ドキュメントの再利用 と継承の説明に従って、ドキュメント コンシューマーは継承されたコンテンツを解決する必要があります。

• -warnon:3390 が使用されている場合でも、F# コンパイラでは相互参照はチェックされません。

• タグ <typeparam> および <typeparamref> で使用される名前は、--warnon:3390 が使用されている場合でも、F# コンパイラによってチェックされません。

• --warnon:3390 が使用されている場合でも、ドキュメントがない場合は警告は表示されません。

推奨 事項

コードの文書化は、さまざまな理由で推奨されます。 次に示すのは、ベスト プラクティス、一般的なユース ケース シナリオ、F# コードで XML ドキュメント タグを使用する場合に知っておくべきことです。

• XML ドキュメントが有効な XML であることを確認するために、コードでオプション --warnon:3390 を有効にします。

• 署名ファイルを追加して、長い XML ドキュメント コメントを実装から分離することを検討してください。

• 一貫性を確保するために、公開されているすべての型とそのメンバーを文書化する必要があります。 やらなければならないなら、すべてやり遂げる。

• 少なくとも、モジュール、型、およびそのメンバーには、プレーンな /// コメントまたは <summary> タグが必要です。 F# 編集ツールのオートコンプリート ツールヒント ウィンドウに表示されます。

• ドキュメントテキストは、完全な文を使用し、句点で終わる必要があります。

関連項目

• C# XML ドキュメント コメント (C# プログラミング ガイド)。
• F# 言語リファレンス
• コンパイラ オプション