记录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 }

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