记录 F# 代码答案

【问题标题】：Documenting F# Code记录 F# 代码
【发布时间】：2013-02-27 20:33:12
【问题描述】：

在具有单个构造函数的 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# 中使用。我的问题是如何将它们添加到上面的 sn-p 中，以便记录类型和构造函数。

【问题讨论】：

+1 好收获。我认为没有办法做到这一点:-(

标签： f# xml-documentation

【解决方案1】：

我查看了source of the open-source F# compiler，我认为 Dr_Asik 是正确的 - 无法使用 XML 注释记录隐式构造函数。代表 AST 中的隐式构造函数的节点（参见 ast.fs 中的 ImplicitCtor here）不包含用于检索 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，以便可以从公共构造函数中调用它。无论如何，我认为这应该被视为一个语言错误，所以我建议将此报告给fsbugsmicrosoft dot com。

顺便说一句，我认为 XML 文档主要用作 IntelliSense 的数据源（尽管它仍然需要构造函数的文档），并且我创建了一些替代的 F# 工具，让您可以通过编写一个带有使用 Markdown 的特殊 cmets 的 F# 脚本文件（有一个 blog post about it） - 所以您可以认为这是对标准 XML 工具的有用补充。

【讨论】：

谢谢，这是我首选的解决方法，尽管我同意这是一个语言错误。我已经提交了一份报告。
嘿 Tomas，我尝试了这种方法，虽然它确实将 Intellisense 添加到构造函数本身，但我无法在独立字段上看到 Intellisense。你有什么想法吗？我正在考虑尝试破解一个 VS 扩展，以帮助解决我在 C# 中非常怀念的一些智能感知完整性。
这似乎不再是这种情况。根据文档，您现在可以在类名之后和隐式构造函数参数列表之前添加 XML doc cmets。docs.microsoft.com/en-us/dotnet/fsharp/language-reference/…

【解决方案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)

【讨论】：

对不起，我的问题应该更清楚，这只是关于如何记录类型摘要和主构造函数。没有办法记录主构造函数似乎很疯狂——这意味着没有人可以使用标准工具记录他们的 F# API。

【解决方案3】：

无法在 F# 源文件 (.fs) 中使用 XML 注释记录隐式构造函数。一种解决方法是显式声明构造函数（参见 Asik 博士的回答）。另一种方法是将您的 XML cmets 放入 F# 签名文件 (.fsi)。

文件.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>

【讨论】：

谢谢，这是一个有趣的选择。我隐约知道 fsi 文件，但没有正确调查它们。但是，为了便于使用，我更喜欢 Tomas 的建议。

【解决方案4】：

这确实是一个烦人的问题。我最终使用的另一个解决方案是不依赖主构造函数：

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

更详细，但不需要额外的文件或私有构造函数...

【讨论】：