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

问题描述

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

////<总结>///这个类会解决你所有的问题///公开课很棒{///<总结>///初始化 <see cref="Awesome"/> 的新实例班级.///</总结>///<param name="sauce">秘制酱料.</param>公共很棒(串酱){//...出于安全目的省略了实现}}

如何对等效的 F# 类执行相同的操作，以便生成的文档相同?

type Awesome(sauce: string) =//...出于安全目的省略了实现

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

解决方案

我查看了开源 F# 编译器的源代码 我认为 Dr_Asik 是对的 - 没有办法用 XML 注释记录隐式构造函数.表示 AST 中隐式构造函数的节点(参见 ast.fs 中的 ImplicitCtor 此处) 不包括用于 stroing XML 文档的字段(表示为 PreXmlDoc 类型).

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

type MyType private(a:int, u:unit) =///<summary>创建MyType</summary>///<param name="a">参数A</param>new(a:int) = MyType(a, ())

我在隐式构造函数中添加了一个虚拟参数u，以便可以从公共构造函数中调用它.无论如何，我认为这应该被视为语言错误，因此我建议将其报告给 microsoft dot com 上的 fsbugs.

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

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

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.

解决方案

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).

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, ())

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.

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屋！