Документирование дискриминационных союзов в F #

Question

Есть ли «лучшие практики» для документирования Дискриминационных союзов в F #? Я использовал теги XML, доступные на MSDN website, но нет никаких упоминаний о документировании DU, кроме тегов <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, то инструмент документации также поддерживает Markdown в комментариях XML, так что можно написать, например:

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

и вы получите каждый комментарий в подсказке при наведении курсора мыши на соответствующее имя типа.