Documentación del código con comentarios XML

Puede generar documentación a partir de comentarios de código de triple barra diagonal (///) en F#. Los comentarios XML pueden preceder a declaraciones en archivos de código (.fs) o archivos de firma (.fsi).

Los comentarios de documentación XML son un tipo especial de comentarios que se agregan encima de la definición de un tipo o un miembro definido por el usuario. Son especiales porque los puede procesar el compilador para generar un archivo de documentación XML en tiempo de compilación. El archivo XML generado por el compilador se puede distribuir junto con el ensamblado de .NET para que los IDE puedan usar información sobre herramientas para mostrar información rápida sobre tipos o miembros. Además, el archivo XML se puede ejecutar a través de herramientas como fsdocs para generar sitios web de referencia de API.

El compilador omite los comentarios de documentación XML, como todos los demás, a menos que las opciones descritas a continuación estén habilitadas para comprobar la validez y la integridad de los comentarios en tiempo de compilación.

Para generar el archivo XML en tiempo de compilación, realice una de las siguientes acciones:

• Puede agregar un elemento a la sección del archivo de proyecto, que genera un archivo XML en el directorio del proyecto con el mismo nombre de archivo GenerateDocumentationFile <PropertyGroup> raíz que el .fsproj ensamblado. Por ejemplo:

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

  Para obtener más información, vea GenerateDocumentationFile, propiedad.

• Si está desarrollando una aplicación mediante Visual Studio, haga clic con el botón derecho en el proyecto y seleccione Propiedades. En el cuadro de diálogo de propiedades, seleccione la pestaña Compilar y active Archivo de documentación XML. También puede cambiar la ubicación en la que el compilador escribe el archivo.

Hay dos maneras de escribir comentarios de documentación XML: con y sin etiquetas XML. Ambos usan comentarios de triple barra diagonal.

Comentarios sin etiquetas XML

Si un comentario no comienza con , todo el texto del comentario se toma como la documentación de resumen de la construcción de código que /// < sigue inmediatamente. Use este método cuando desee escribir solo un breve resumen para cada construcción.

El comentario se codifica en XML durante la preparación de la documentación, por lo que no es necesario que se escapen caracteres como < > , y & . Si no especifica una etiqueta de resumen explícitamente, no debe especificar otras etiquetas, como param o returns tags.

En el ejemplo siguiente se muestra el método alternativo, sin etiquetas XML. En este ejemplo, todo el texto del comentario se considera un resumen.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

Comentarios con etiquetas XML

Si un cuerpo de comentario comienza por (normalmente ), se trata como un cuerpo de comentario con formato < <summary> XML mediante etiquetas XML. Este segundo le permite especificar notas independientes para un breve resumen, comentarios adicionales, documentación para cada parámetro y parámetro de tipo y excepciones producidas, y una descripción del valor devuelto.

A continuación se muestra un comentario típico de documentación XML en un archivo de firma:

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

Etiquetas recomendadas

Si usa etiquetas XML, en la tabla siguiente se describen las etiquetas externas reconocidas en los comentarios de código XML de F#.

En la tabla siguiente se describen las etiquetas para su uso dentro de las secciones de descripción:

Etiquetas definidas por el usuario

Las etiquetas anteriores representan las que reconoce el compilador de F# y las herramientas típicas del editor de F#. pero el usuario puede definir sus propias etiquetas. Herramientas como fsdocs admiten etiquetas adicionales como <namespacedoc> . También se pueden usar herramientas de generación de documentación internas o personalizadas con las etiquetas estándar y se admiten varios formatos de salida, de HTML a PDF.

Comprobación en tiempo de compilación

Cuando está habilitado, el compilador comprueba la sintaxis del XML y los parámetros a los que se hace --warnon:3390 referencia en las <param> <paramref> etiquetas y .

Documentar construcciones de F#

Las construcciones de F#, como módulos, miembros, casos de unión y campos de registro, se documentan mediante un comentario inmediatamente antes /// de su declaración. Si es necesario, los constructores implícitos de clases se documentan al dar un /// comentario antes de la lista de argumentos. Por ejemplo:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Limitaciones

Algunas características de la documentación XML en C# y otros lenguajes .NET no se admiten en F#.

• En F#, las referencias cruzadas deben usar la firma XML completa del símbolo correspondiente, por ejemplo cref="T:System.Console" . Las referencias cruzadas simples de estilo C#, como , no se elaboran para firmas XML completa y el compilador de F# no comprueba cref="Console" estos elementos. Algunas herramientas de documentación pueden permitir el uso de estas referencias cruzadas mediante el procesamiento posterior, pero se deben usar las firmas completa.

• El compilador <include> <inheritdoc> de F# no admite las etiquetas . No se produce ningún error si se usan, pero simplemente se copian en el archivo de documentación generado sin que ello afecte a la documentación generada.

• El compilador de F# no comprueba las referencias cruzadas, incluso cuando -warnon:3390 se usa .

• El compilador de F# no comprueba los nombres usados en las <typeparam> etiquetas, incluso cuando se usa <typeparamref> --warnon:3390 .

• No se muestra ninguna advertencia si falta documentación, incluso cuando --warnon:3390 se usa.

Recomendaciones

Se recomienda documentar código por diversos motivos. A continuación se deberán conocer algunos procedimientos recomendados, escenarios de casos de uso generales y aspectos que debe conocer al usar etiquetas de documentación XML en el código de F#.

• Habilite la opción --warnon:3390 en el código para ayudar a asegurarse de que la documentación XML es XML válido.

• Considere la posibilidad de agregar archivos de firma para separar los comentarios largos de documentación XML de la implementación.

• Por motivos de coherencia, se deben documentar todos los tipos públicamente visibles y sus miembros. Si debe hacerlo, hágalo en todos los elementos.

• Como mínimo, los módulos, los tipos y sus miembros deben tener un comentario /// o una etiqueta sin <summary> formato. Esto se mostrará en una ventana de información sobre herramientas de autocompletar en las herramientas de edición de F#.

• El texto de la documentación se debe escribir con frases completas que terminen en punto.

Vea también

• Comentarios de documentación XML de C# (guía de programación# C).
• Referencia del lenguaje F#
• Opciones del compilador