Documenting discriminated unions in F#

Question

Is there a "best practices" for documenting Discriminated Unions in F#? I've been using the XML tags available at the MSDN website, but there's no mention on documenting DUs, other than the <typeparam name = "x"> Desc. </typeparam> tags.

The tags are helpful for standard types and functions, but which XML tags should be used for DUs?

Answer 1

I mostly just use the <summary> tag for the type and for all its members (and since the compiler adds <summary> automatically, this means I don't have to write any XML by hand):

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

It might be just me, but I find that filing all the other tags is just too much work and it does not give you that much more information.

If you were using F# ProjectScaffold, then the documentation tool also supports Markdown in the XML comments, and so you could write for example:

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

At the moment, this does not show very nicely in Visual Studio tooltips, but if you are writing a library and want to have a great documentation for it, then this is a good way to get it.

Answer 2

Each union member is, in effect, its own type, and it can have its own XML comment documentation. So you can write a DU like this:

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

and you'll get each comment in the tooltip when hovering over the appropriate type name.