记录F#代码 [英] Documenting F# Code

问题描述

在具有单个构造函数的C#类中，我可以添加类摘要XML文档和构造函数XML文档:

In a C# class with a single constructor, I can add class summary XML documentation and constructor XML documentation:

///<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#类执行相同的操作，以使生成的文档相同?

How do I do the same with the equivalent F# class such that the generated documentation is the same?

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

说明:我知道标准的XML文档标记可以在F#中使用.我的问题是如何将它们添加到上述代码段中，以便记录类型和构造函数.

CLARIFICATION: I'm aware that the standard XML documentation tags can be used in F#. My question is how to add them to the above snippet so that both the type and the constructor are documented.

推荐答案

我查看了开源F#编译器的源代码并且我认为Dr_Asik是正确的-无法用XML注释记录隐式构造函数.代表AST中隐式构造函数的节点(请参见ast.fs ImplicitCtor >此处)不包含用于存储XML文档的字段(表示为PreXmlDoc类型).

I looked at the source of the open-source F# compiler and I think Dr_Asik is right - there is no way of documenting the implicit constructor with an XML comment. The node that represents the implicit constructor in the AST (See ImplicitCtor in ast.fs here) does not include a field for stroing the XML documentation (represented as PreXmlDoc type).

您仍然可以记录所有公共API-您必须使用Dr_Asik提到的和方法，将隐式构造函数标记为private.我同意这有点难看，但我认为这比不使用隐式构造函数更方便:

You can still document all public API - you'd have to use the method that Dr_Asik mentioned and mark the implicit constructor as private. I agree this is a bit ugly, but I think it is more convenient than not using implicit constructors:

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.

I added a dummy parameter u to the implicit constructor, so that it can be called from the public constructor. Anyway, I think this should be considered as a language bug and so I'd suggest reporting this to fsbugs at microsoft dot com.

顺便说一句，我认为XML文档主要用作IntelliSense的数据源(尽管它仍然需要构造函数的文档)，并且我创建了一些替代性的F#工具，使您可以通过编写一个F#工具来创建教程和文档.使用Markdown的带有特殊注释的F#脚本文件(有关于它的博客文章)-因此您可以考虑这是对标准XML工具的有用补充.

As an aside, I think the XML documentation is mainly useful as a source of data for IntelliSense (which still needs documentation for the constructor, though) and I created some alternative F# tools that let you create tutorials and documentation by writing an F# script file with special comments using Markdown (there is a blog post about it) - so you may consider that as a useful addition to the standard XML tooling.

这篇关于记录F#代码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！