Documentare F # Codice

Question

In una classe C# con un unico costruttore, posso aggiungere sintesi di classe documentazione XML e la documentazione costruttore di XML:

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

Come posso fare lo stesso con l'equivalente F # di classe in modo che la documentazione generata è la stessa?

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

CHIARIMENTO: Sono consapevole che i tag di documentazione XML standard possono essere utilizzati in F #. La mia domanda è come aggiungerli allo snippet sopra in modo che sia il tipo sia il costruttore siano documentati.

Answer 1

ho guardato le source of the open-source F# compiler e penso Dr_Asik è giusto - non c'è modo di documentare il costruttore implicita con un commento XML. Il nodo che rappresenta il costruttore implicito nell'AST (vedere ImplicitCtor in ast.fshere) non include un campo per l'accodamento della documentazione XML (rappresentato come tipo PreXmlDoc).

È ancora possibile documentare tutte le API pubbliche: è necessario utilizzare il metodo che Dr_Asik ha citato e contrassegnare il costruttore implicito come private. Sono d'accordo che questo è un po 'brutto, ma penso che sia più conveniente che non si utilizza costruttori impliciti:

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

ho aggiunto un parametro fittizio u al costruttore implicita, in modo che possa essere chiamato dal costruttore pubblico. Ad ogni modo, penso che questo dovrebbe essere considerato un bug di linguaggio e quindi suggerirei di riportarlo a fsbugs allo microsoft punto com.

Per inciso, penso che la documentazione XML sia principalmente utile come fonte di dati per IntelliSense (che tuttavia richiede ancora la documentazione per il costruttore) e ho creato alcuni strumenti alternativi di F # che consentono di creare tutorial e documentazione scrivendo un file di script F # con commenti speciali usando Markdown (c'è un blog post about it) - quindi potresti considerarlo come un'aggiunta utile agli strumenti XML standard.

Answer 2

Esattamente nello stesso modo come si fa in C#: http://msdn.microsoft.com/en-us/library/dd233217.aspx

Se non mettete nessun tag, F # assume è "sintesi":

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

... è equivalente a

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

Se si desidera documentare un costruttore, è necessario dichiararlo in modo esplicito. AFAIK non c'è modo di documentare il costruttore principale.

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

Answer 3

Non esiste alcun modo per documentare il costruttore implicito con un commento XML all'interno di un file di origine F # (.fs). Una soluzione alternativa è dichiarare esplicitamente il costruttore (vedere la risposta del dott. Asik). Un altro è quello di inserire i tuoi commenti XML in un 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 

La documentazione XML per questa assemblea conterrà ora la corretta sintesi:

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

Answer 4

Questo è davvero un fastidioso problema. Un'altra soluzione che ho finito per usare è quello di non fare affidamento su un costruttore principale:

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

più prolisso, ma nessun file aggiuntivi o costruttori privati ​​necessaria ...