26

単一のコンストラクターを持つ C# クラスでは、クラス サマリー XML ドキュメントとコンストラクター XML ドキュメントを追加できます。

///<summary>
///This class will solve all your problems
///</summary>
public class Awesome
{
    /// <summary>
    /// Initializes a new instance of the <see cref="Awesome"/> class.
    /// </summary>
    /// <param name="sauce">The secret sauce.</param>       
    public Awesome(string sauce)
    {
        //...implementation elided for security purposes
    }
}

生成されたドキュメントが同じになるように、同等の F# クラスで同じことを行うにはどうすればよいですか?

type Awesome(sauce: string) = 
    //...implementation elided for security purposes

明確化: 標準の XML ドキュメント タグを F# で使用できることは承知しています。私の質問は、型とコンストラクターの両方が文書化されるように、それらを上記のスニペットに追加する方法です。

4

4 に答える 4

17

オープンソースの F# コンパイラのソースを調べたところ、Dr_Asik が正しいと思います。暗黙のコンストラクターを XML コメントで文書化する方法はありません。AST で暗黙のコンストラクターを表すノード (ここImplicitCtorを参照)には、XML ドキュメント (型として表される) をストーミングするためのフィールドが含まれていません。ast.fs PreXmlDoc

すべてのパブリック API を文書化することもできます。Dr_Asik が言及したメソッドを使用し、暗黙のコンストラクターを としてマークする必要がありprivateます。これは少し醜いことに同意しますが、暗黙のコンストラクターを使用しないよりは便利だと思います。

type MyType private(a:int, u:unit) =
  /// <summary>Creates MyType</summary>
  /// <param name="a">Parameter A</param>
  new(a:int) = MyType(a, ())

uパブリック コンストラクターから呼び出せるように、暗黙のコンストラクターにダミー パラメーターを追加しました。とにかく、これは言語のバグと見なされるべきだと思うので、これをfsbugsat microsoftdotに報告することをお勧めしcomます。

余談ですが、XML ドキュメントは主に IntelliSense のデータ ソースとして役立つと思います (ただし、コンストラクターのドキュメントはまだ必要です)。F# スクリプト ファイルを記述してチュートリアルとドキュメントを作成できる代替の F# ツールをいくつか作成しました。 Markdown を使用した特別なコメント付き (それに関するブログ投稿があります) - 標準 XML ツールへの便利な追加機能と考えることができます。

于 2013-02-28T02:12:19.253 に答える
14

C# の場合とまったく同じ方法: http://msdn.microsoft.com/en-us/library/dd233217.aspx

タグを付けない場合、F# はそれが「要約」であると想定します。

/// This is the documentation
type MyType() = ....

...と同等です

/// <summary>This is the documentation</summary>
type MyType() = ...

コンストラクターを文書化する場合は、明示的に宣言する必要があります。私の知る限り、プライマリコンストラクターを文書化する方法はありません。

/// [Type summary goes here]
type MyType(a : int) =
    let m_a = a
    /// [Parameterless constructor documentation here]
    new() = MyType(0)
于 2013-02-27T20:37:33.180 に答える
9

F＃ソースファイル（.fs）内のXMLコメントを使用して暗黙のコンストラクターを文書化する方法はありません。回避策の1つは、コンストラクターを明示的に宣言することです（Asik博士の回答を参照）。もう1つは、XMLコメントをF＃署名ファイル（.fsi）に入れることです。

File.fs：

module File

type Awesome(sauce: string) =
    member x.Sauce = sauce

File.fsi

module File

type Awesome =
  class
    /// Implicit constructor summary for the Awesome type
    new : sauce:string -> Awesome
    member Sauce : string
  end

このアセンブリのXMLドキュメントには、正しい要約が含まれています。

<member name="M:File.Awesome.#ctor(System.String)">
<summary>
 Implicit constructor summary for the Awesome type
</summary>
</member>
于 2013-02-28T14:55:19.727 に答える
4

これは本当に厄介な問題です。私が最終的に使用した別の解決策は、プライマリ コンストラクターに依存しないことです。

/// Documentation type.
type Awesome =
    val sauce : string
    /// <summary>Documentation constructor.</summary>
    /// <param name="sauce">Sauce. Lots of it.</param>
    new (sauce) = { sauce = sauce }

より冗長ですが、追加のファイルやプライベート コンストラクターは必要ありません...

于 2013-08-05T14:20:14.003 に答える