Documentando el código F#

xml-documentation

Question

En una clase de C # con un único constructor, puedo agregar documentación de resumen de clase XML y documentación de constructor 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
    }
}

¿Cómo hago lo mismo con la clase F # equivalente de manera que la documentación generada sea la misma?

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

ACLARACIÓN: Soy consciente de que las etiquetas de documentación XML estándar se pueden usar en F #. Mi pregunta es cómo agregarlos al fragmento anterior para que tanto el tipo como el constructor estén documentados.

Answer 1

De la misma manera que lo hace en C #: http://msdn.microsoft.com/en-us/library/dd233217.aspx

Si no coloca ninguna etiqueta, F # asume que es "resumen":

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

... es equivalente a

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

Si desea documentar un constructor, deberá declararlo explícitamente. AFAIK no hay forma de documentar el constructor primario.

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

Answer 2

Esto realmente es un problema molesto. Otra solución que terminé usando es no confiar en un constructor primario:

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

Más detallado, pero no se necesitan archivos adicionales ni constructores privados ...

Answer 3

Miré la fuente del compilador F # de código abierto y creo que Dr_Asik tiene razón: no hay forma de documentar el constructor implícito con un comentario XML. El nodo que representa el constructor implícito en el AST (vea ImplicitCtor en ast.fs here ) no incluye un campo para trazar la documentación XML (representada como tipo PreXmlDoc ).

Aún puede documentar todas las API públicas; tendría que usar el método que mencionó Dr_Asik y marcar el constructor implícito como private . Estoy de acuerdo en que esto es un poco feo, pero creo que es más conveniente que no usar constructores implícitos:

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

Agregué un parámetro ficticio u al constructor implícito, para que pueda llamarse desde el constructor público. De todos modos, creo que esto debería considerarse como un error de idioma y, por lo tanto, sugeriría informar esto a fsbugs en microsoft dot com .

Además, creo que la documentación XML es principalmente útil como fuente de datos para IntelliSense (que aún necesita documentación para el constructor) y creé algunas herramientas alternativas de F # que le permiten crear tutoriales y documentación escribiendo un archivo de script F # con comentarios especiales utilizando Markdown (hay una publicación de blog al respecto ), por lo que puede considerar eso como una adición útil a las herramientas XML estándar.

Answer 4

No hay forma de documentar el constructor implícito con un comentario XML dentro de un archivo fuente F # (.fs). Una solución es declarar explícitamente el constructor (ver la respuesta del Dr. Asik). Otra es colocar sus comentarios XML en un archivo de firma F # (.fsi).

File.fs:

module File

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

Archivo.fsi

module File

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

La documentación XML para este ensamblaje ahora contendrá el resumen correcto:

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