Question

是否有用于记录F＃中的歧视联盟的“最佳做法”？我一直在使用MSDN website上提供的XML标记，但除了<typeparam name = "x"> Desc. </typeparam>标记之外，没有提及记录DU。

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

Answer 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注释中的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工具提示中并没有很好地显示，但是如果你正在编写一个库并希望有一个很好的文档，那么这是获得它的好方法。

Answer 2

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

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

当您将鼠标悬停在相应的类型名称上时，您将在工具提示中获得每条评论。

在F＃中记录受歧视的工会

2 个答案: