記錄F＃代碼

Question

在具有單個構造函數的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＃中使用。 我的問題是如何將它們添加到上面的代碼片段，以便記錄類型和構造函數。

Answer 1

我查看了開源F＃編譯器的來源 ，我認為Dr_Asik是對的 - 沒有辦法用XML注釋記錄隱式構造函數。 表示AST中隱式構造函數的節點（請參見此處的 ast.fs ImplicitCtor ）不包含用於PreXmlDoc XML文檔的字段（表示為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 ，以便可以從公共構造函數中調用它。 無論如何，我認為這應該被視為語言錯誤，所以我建議在microsoft dot com向fsbugs報告。

順便說一句，我認為XML文檔主要用作IntelliSense的數據源（雖然仍然需要構造函數的文檔），我創建了一些替代的F＃工具，可以通過編寫F＃腳本文件來創建教程和文檔。使用Markdown的特殊評論（有關於它的博客文章 ） - 因此您可以將其視為標准XML工具的有用補充。

Answer 2

與您在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() = ...

如果要記錄構造函數，則必須明確聲明它。 AFAIK沒有辦法記錄主要構造函數。

/// [Type summary goes here]
type MyType(a : int) =
    let m_a = a
    /// [Parameterless constructor documentation here]
    new() = MyType(0)

Answer 3

無法在F＃源文件（.fs）中使用XML注釋來記錄隱式構造函數。 一種解決方法是明確聲明構造函數（參見Dr Asik的答案）。 另一種方法是將您的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>

Answer 4

這確實是一個惱人的問題。 我最終使用的另一個解決方案是不依賴於主構造函數：

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

更詳細，但不需要額外的文件或私有構造函數......