Documentación del código con comentarios XML

Artículo
03/09/2023

Se puede generar documentación a partir de los comentarios de triple barra (///) código 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 .NET de modo que los IDE puedan usar herramientas para mostrar información rápida sobre los tipos o los miembros. Además, el archivo XML se puede ejecutar mediante 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 comentarios, 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:

Puedes agregar un GenerateDocumentationFile elemento a la <PropertyGroup> sección del archivo de .fsproj proyecto, que genera un archivo XML en el directorio del proyecto con el mismo nombre de archivo raíz que el ensamblado. Por ejemplo:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Para más información, consulta la propiedad GenerateDocumentationFile.
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 barra diagonal triple.

Comentarios sin etiquetas XML

Si un /// comentario no comienza con <, se toma todo el texto del comentario 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 especificas explícitamente una etiqueta de resumen, no debe especificar otras etiquetas, como parámetros o etiquetas de devolución.

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 <summary>), se trata como un cuerpo de comentario con formato XML mediante etiquetas XML. Esta segunda manera permite especificar notas independientes para un breve resumen, comentarios adicionales, documentación para cada parámetro y parámetro de tipo y excepciones iniciadas y una descripción del valor devuelto.

A continuación se muestra un comentario de documentación XML típico 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 usas etiquetas XML, en la tabla siguiente se describen las etiquetas externas reconocidas en los comentarios de código XML de F#.

Sintaxis de etiquetas	Descripción
`<summary>`*texto*`</summary>`	Especifica que el texto es una breve descripción del elemento program. La descripción suele ser una o dos oraciones.
`<remarks>`*texto*`</remarks>`	Especifica que el texto contiene información complementaria sobre el elemento program.
`<param name="`*nombre`">`descripción*`</param>`	Especifica el nombre y la descripción de una función o un parámetro de método.
`<typeparam name="`*nombre`">`descripción*`</typeparam>`	Especifica el nombre y la descripción de un parámetro de tipo.
`<returns>`*texto*`</returns>`	Especifica que el texto describe el valor devuelto de una función o método.
`<exception cref="`*tipo`">`descripción*`</exception>`	Especifica el tipo de excepción que se puede generar y las circunstancias en las que se produce.
`<seealso cref="`*referencia*`"/>`	Especifica un vínculo Ver también a la documentación de otro tipo. La referencia es el nombre tal y como aparece en el archivo de documentación XML. Consulta también los vínculos aparecen normalmente en la parte inferior de una página de documentación.

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

Sintaxis de etiquetas	Descripción
`<para>`*texto*`</para>`	Especifica un párrafo de texto. Se usa para separar el texto dentro de la etiqueta de comentarios.
`<code>`*texto*`</code>`	Especifica que el texto está formado por varias líneas de código. Los generadores de documentación pueden usar esta etiqueta para mostrar texto en una fuente adecuada para el código.
`<paramref name="`*nombre*`"/>`	Especifica una referencia a un parámetro en el mismo comentario de documentación.
`<typeparamref name="`*nombre*`"/>`	Especifica una referencia a un parámetro de tipo en el mismo comentario de documentación.
`<c>`*texto*`</c>`	Especifica que el texto es código insertado. Los generadores de documentación pueden usar esta etiqueta para mostrar texto en una fuente adecuada para el código.
`<see cref="`*referencia`">`texto*`</see>`	Especifica un vínculo insertado a otro elemento de programa. La referencia es el nombre tal y como aparece en el archivo de documentación XML. El texto es el texto que se muestra en el vínculo.

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 proporcionan compatibilidad con 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.

Comprobaciones en tiempo de compilación

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

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 proporcionando 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". El compilador de F# no comprueba las referencias cruzadas simples de estilo C#, como cref="Console" las firmas XML completas y estos elementos no se comprueban mediante el compilador de F#. Algunas herramientas de documentación pueden permitir el uso de estas referencias cruzadas mediante el procesamiento posterior, pero se deben usar las firmas completas.
El compilador de F# no admite las etiquetas <include>, <inheritdoc>. No se da 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 etiquetas <typeparam> y <typeparamref> no se comprueban, incluso cuando --warnon:3390 se usa.
No se proporcionan advertencias si falta documentación, incluso cuando --warnon:3390 se usa.

Recomendaciones

Se recomienda documentar código por diversos motivos. A continuación se muestran algunos procedimientos recomendados, escenarios generales de casos de uso y conceptos 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 asegurarse de que la documentación XML es XML válida.
Considere la posibilidad de agregar archivos de firma a comentarios de documentación XML largos 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 <summary>etiqueta sin 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.

Compartir vía