Documenting F# Code

Question

In a C# class with a single constructor, I can add class summary XML documentation and constructor XML documentation:

///<summary>
///This class will solve all your problems
///</summary>
public class Awesome
{
    /// <summary>
    /// Initializes a new instance of the <see cref="Awesome"/> class.
    /// </summary>
    /// <param name="sauce">The secret sauce.</param>       
    public Awesome(string sauce)
    {
        //...implementation elided for security purposes
    }
}

How do I do the same with the equivalent F# class such that the generated documentation is the same?

type Awesome(sauce: string) = 
    //...implementation elided for security purposes

CLARIFICATION: I'm aware that the standard XML documentation tags can be used in F#. My question is how to add them to the above snippet so that both the type and the constructor are documented.

Answer 1

I looked at the source of the open-source F# compiler and I think Dr_Asik is right - there is no way of documenting the implicit constructor with an XML comment. The node that represents the implicit constructor in the AST (See ImplicitCtor in ast.fs here) does not include a field for stroing the XML documentation (represented as PreXmlDoc type).

You can still document all public API - you'd have to use the method that Dr_Asik mentioned and mark the implicit constructor as private. I agree this is a bit ugly, but I think it is more convenient than not using implicit constructors:

type MyType private(a:int, u:unit) =
  /// <summary>Creates MyType</summary>
  /// <param name="a">Parameter A</param>
  new(a:int) = MyType(a, ())

I added a dummy parameter u to the implicit constructor, so that it can be called from the public constructor. Anyway, I think this should be considered as a language bug and so I'd suggest reporting this to fsbugs at microsoft dot com.

As an aside, I think the XML documentation is mainly useful as a source of data for IntelliSense (which still needs documentation for the constructor, though) and I created some alternative F# tools that let you create tutorials and documentation by writing an F# script file with special comments using Markdown (there is a blog post about it) - so you may consider that as a useful addition to the standard XML tooling.

Answer 2

In exactly the same way as you do in C#: http://msdn.microsoft.com/en-us/library/dd233217.aspx

If you don't put any tags, F# assumes it is "summary":

/// This is the documentation
type MyType() = ....

... is equivalent to

/// <summary>This is the documentation</summary>
type MyType() = ...

If you want to document a constructor, you'll have to declare it explicitely. AFAIK there is no way to document the primary constructor.

/// [Type summary goes here]
type MyType(a : int) =
    let m_a = a
    /// [Parameterless constructor documentation here]
    new() = MyType(0)

Answer 3

There is no way to document the implicit constructor with an XML comment inside an F# source file (.fs). One workaround is to declare the constructor explicitly (see Dr Asik's answer). Another is to put your XML comments into an F# Signature File (.fsi).

File.fs:

module File

type Awesome(sauce: string) =
    member x.Sauce = sauce

File.fsi

module File

type Awesome =
  class
    /// Implicit constructor summary for the Awesome type
    new : sauce:string -> Awesome
    member Sauce : string
  end

The XML documentation for this assembly will now contain the correct summary:

<member name="M:File.Awesome.#ctor(System.String)">
<summary>
 Implicit constructor summary for the Awesome type
</summary>
</member>

Answer 4

This really is an annoying problem. Another solution I ended up using is to not rely on a primary constructor:

/// Documentation type.
type Awesome =
    val sauce : string
    /// <summary>Documentation constructor.</summary>
    /// <param name="sauce">Sauce. Lots of it.</param>
    new (sauce) = { sauce = sauce }

More verbose, but no extra files or private constructors needed...