在F＃中記錄受歧視的工會

Question

是否有一個“最佳實踐”來記錄F＃中的歧視聯盟？ 我一直在使用MSDN網站上提供的XML標簽，但除了<typeparam name = "x"> Desc. </typeparam>之外，沒有提及記錄<typeparam name = "x"> Desc. </typeparam> <typeparam name = "x"> Desc. </typeparam>標簽。

標簽對標准類型和功能很有用，但是哪些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

當鼠標懸停在相應的類型名稱上時，您將在工具提示中獲得每條評論。