[英]Documenting discriminated unions in F#
是否有一个“最佳实践”来记录F#中的歧视联盟? 我一直在使用MSDN网站上提供的XML
标签,但除了<typeparam name = "x"> Desc. </typeparam>
之外,没有提及记录<typeparam name = "x"> Desc. </typeparam>
<typeparam name = "x"> Desc. </typeparam>
标签。
标签对标准类型和功能很有用,但是哪些XML
标签应该用于DU?
我大多只使用<summary>
标签作为类型及其所有成员(并且由于编译器自动添加<summary>
,这意味着我不必手动编写任何XML):
/// Represents a thumbnail that will appear on the movie web site
type MovieThumbnail =
/// Use a PNG image at the specified URL
| Image of string
/// Use a default image for the specified genre
| Default of Genre
它可能只是我,但我发现归档所有其他标签只是太多的工作,它不会给你更多的信息。
如果您使用的是F#ProjectScaffold ,那么文档工具也支持XML注释中的Markdown,因此您可以编写例如:
/// Represents a thumbnail that will appear on the movie web site
///
/// ## Example
/// The following shows simple pattern matching:
///
/// match movieThumb with
/// | Image(url) -> sprintf "<img src='%s' />" url
/// | Default(g) -> defaultImageFor g
///
type MovieThumbnail =
/// Use a PNG image at the specified URL
| Image of string
/// Use a default image for the specified genre
| Default of Genre
目前,这在Visual Studio工具提示中并没有很好地显示,但是如果你正在编写一个库并希望有一个很好的文档,那么这是一个很好的方法来获得它。
实际上,每个联合成员都是它自己的类型,它可以有自己的XML注释文档。 所以你可以像这样写一个DU:
/// Explain Foo here
type Foo =
/// Explain Bar here
| Bar
/// Explain Baz here
| Baz
当鼠标悬停在相应的类型名称上时,您将在工具提示中获得每条评论。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.