歸檔F＃代碼

在具有單個構造函數C＃類，我可以添加類摘要XML文檔和構造XML文檔：歸檔F＃代碼

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

來源

2013-02-27 Akash

+1良好的漁獲物。我不認爲有辦法做到這一點:-( – 2013-02-28 02:12:56

我看着source of the open-source F# compiler，我認爲Dr_Asik是正確的 - 沒有與XML註釋記錄了隱式構造的方式。表示AST中隱式構造函數的節點（請參閱ImplicitCtor中的ast.fshere）不包含用於stroing 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隱式的構造函數，以便它可以從公共構造函數被調用。無論如何，我認爲這應該被視爲一種語言錯誤，所以我建議報告這個fsbugs在microsoft點com。另一方面，我認爲XML文檔主要用作IntelliSense數據源（雖然仍然需要構造函數的文檔），並且我創建了一些可供選擇的F＃工具，可以通過編寫創建教程和文檔一個帶有使用Markdown的特殊註釋的F＃腳本文件（有一個blog post about it） - 所以您可以認爲這是對標準XML工具的有用補充。

來源

2013-02-28 02:12:19

謝謝，這是我的首選解決方法，但我同意它是一種語言錯誤，我已經提交了一份報告。 – Akash 2013-03-01 13:58:54

Hey Tomas ，我嘗試了這種方法，雖然它將Intellisense添加到構造函數本身，但我無法在獨立的字段上看到Intellisense。你有什麼想法嗎？我正在考慮嘗試將VS擴展插入到幫助一些intellisense的完整性，我很想念C＃。 – Nuzzolilo 2017-04-21 18:56:35

在完全相同的方式，你在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)

來源

2013-02-27 20:37:33 Asik

對不起，我應該在我的問題更清楚，這只是關於如何記錄類型摘要和主要構造函數。看起來很瘋狂，沒有如何使用標準工具來記錄他們的F＃API – Akash 2013-02-28 00:06:41

無法在F＃源文件（.fs）中使用XML註釋記錄隱式構造函數。一種解決方法是明確聲明構造函數（請參閱Asik博士的回答）。另一種方法是將XML註釋放入F＃簽名文件（.fsi）中。

File.fs：

module File 

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

文件。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-28 14:55:19 petebu

謝謝，這是一個有趣的選項。我隱約知道fsi文件，但沒有正確調查它們。但是，爲了便於使用我更喜歡Tomas的建議。 – Akash 2013-03-01 13:52:27

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

/// 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-05 14:20:14

歸檔F＃代碼

回答

相關問題