在 F# 中记录有区别的联合答案

【问题标题】：Documenting discriminated unions in F#在 F# 中记录有区别的联合
【发布时间】：2015-09-28 15:52:43
【问题描述】：

在 F# 中记录有区别的联合是否有“最佳实践”？我一直在使用MSDN website 提供的XML 标签，但除了<typeparam name = "x"> Desc. </typeparam> 标签之外，没有提及记录DU。

标签对标准类型和功能很有帮助，但哪些XML标签应该用于DU？

【问题讨论】：

标签： f#

【解决方案1】：

我大多只对类型及其所有成员使用<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 cmets 中的 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 工具提示中显示得不是很好，但如果您正在编写一个库并希望有一个很好的文档，那么这是获得它的好方法。

【讨论】：

我真的才刚刚开始接触 F# 和文档库的皮毛，而 F# ProjectScaffold 看起来确实很有用。

【解决方案2】：

实际上，每个联合成员都有自己的类型，并且可以拥有自己的 XML 注释文档。所以你可以这样写一个DU：

/// Explain Foo here
type Foo =
/// Explain Bar here
| Bar
/// Explain Baz here
| Baz

当您将鼠标悬停在适当的类型名称上时，您会在工具提示中看到每条评论。

【讨论】：