记录歧视工会在F＃

Question

是否有一个“最佳实践”记录在F＃歧视联盟？我一直在使用XML标签MSDN website，但除了<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注释，所以你可以，例如写：在Visual Studio

/// 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 

目前，这并没有表现出非常漂亮工具提示，但是如果你正在编写一个库，并且希望有一个很好的文档，那么这是获取它的好方法。

Answer 2

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

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

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