[英]Documenting F# Code
In a C# class with a single constructor, I can add class summary XML documentation and constructor XML documentation: 在具有单个构造函数的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
}
}
How do I do the same with the equivalent F# class such that the generated documentation is the same? 如何使用等效的F#类进行相同的操作,以使生成的文档相同?
type Awesome(sauce: string) =
//...implementation elided for security purposes
CLARIFICATION: I'm aware that the standard XML documentation tags can be used in F#. 澄清:我知道标准的XML文档标签可以在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. 我查看了开源F#编译器的来源 ,我认为Dr_Asik是对的 - 没有办法用XML注释记录隐式构造函数。 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). 表示AST中隐式构造函数的节点(请参见此处的
ast.fs
ImplicitCtor
)不包含用于PreXmlDoc
XML文档的字段(表示为PreXmlDoc
类型)。
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
. 你仍然可以记录所有的公共API -你必须使用Dr_Asik提到的方法和标记隐式构造函数为
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. 我向隐式构造函数添加了一个伪参数
u
,以便可以从公共构造函数中调用它。 Anyway, I think this should be considered as a language bug and so I'd suggest reporting this to fsbugs
at microsoft
dot com
. 无论如何,我认为这应该被视为语言错误,所以我建议在
microsoft
dot com
向fsbugs
报告。
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. 顺便说一句,我认为XML文档主要用作IntelliSense的数据源(虽然仍然需要构造函数的文档),我创建了一些替代的F#工具,可以通过编写F#脚本文件来创建教程和文档。使用Markdown的特殊评论(有关于它的博客文章 ) - 因此您可以将其视为标准XML工具的有用补充。
In exactly the same way as you do in C#: http://msdn.microsoft.com/en-us/library/dd233217.aspx 与您在C#中的完全相同: http : //msdn.microsoft.com/en-us/library/dd233217.aspx
If you don't put any tags, F# assumes it is "summary": 如果你没有放任何标签,F#假定它是“摘要”:
/// This is the documentation
type MyType() = ....
... is equivalent to ......相当于
/// <summary>This is the documentation</summary>
type MyType() = ...
If you want to document a constructor, you'll have to declare it explicitely. 如果要记录构造函数,则必须明确声明它。 AFAIK there is no way to document the primary constructor.
AFAIK没有办法记录主要构造函数。
/// [Type summary goes here]
type MyType(a : int) =
let m_a = a
/// [Parameterless constructor documentation here]
new() = MyType(0)
There is no way to document the implicit constructor with an XML comment inside an F# source file (.fs). 无法在F#源文件(.fs)中使用XML注释来记录隐式构造函数。 One workaround is to declare the constructor explicitly (see Dr Asik's answer).
一种解决方法是明确声明构造函数(参见Dr Asik的答案)。 Another is to put your XML comments into an F# Signature File (.fsi).
另一种方法是将您的XML注释放入F#签名文件(.fsi)。
File.fs: File.fs:
module File
type Awesome(sauce: string) =
member x.Sauce = sauce
File.fsi File.fsi
module File
type Awesome =
class
/// Implicit constructor summary for the Awesome type
new : sauce:string -> Awesome
member Sauce : string
end
The XML documentation for this assembly will now contain the correct summary: 此程序集的XML文档现在将包含正确的摘要:
<member name="M:File.Awesome.#ctor(System.String)">
<summary>
Implicit constructor summary for the Awesome type
</summary>
</member>
This really is an annoying problem. 这确实是一个恼人的问题。 Another solution I ended up using is to not rely on a primary constructor:
我最终使用的另一个解决方案是不依赖于主构造函数:
/// Documentation type.
type Awesome =
val sauce : string
/// <summary>Documentation constructor.</summary>
/// <param name="sauce">Sauce. Lots of it.</param>
new (sauce) = { sauce = sauce }
More verbose, but no extra files or private constructors needed... 更详细,但不需要额外的文件或私有构造函数......
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.