Documentar el código con comentarios XML

Artículo
01/03/2025

Puede generar documentación a partir de comentarios de código de triple barra diagonal (///) en el lenguaje 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 comentario, agregado encima de la definición de cualquier tipo o miembro definido por el usuario. Son especiales porque el compilador puede procesarlos 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 a través de herramientas como fsdocs para generar sitios web de referencia de API.

De forma predeterminada, el compilador omite los comentarios de documentación XML. Para cambiar esto, establezca --warnon:3390. A continuación, el compilador comprobará la sintaxis del XML y los parámetros a los que se hace referencia en las etiquetas <param> y <paramref>.

Puede generar el archivo XML en tiempo de compilación realizando una de las siguientes acciones:

Puede agregar un elemento GenerateDocumentationFile a la sección <PropertyGroup> del archivo de proyecto de .fsproj, 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 obtener más información, consulte la propiedad GenerateDocumentationFile.
Si va a desarrollar una aplicación con 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 a 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 un <, el texto completo del comentario se utilizará como la documentación resumida para la estructura de código que sigue inmediatamente. Use este método cuando quiera 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 explícitamente una etiqueta de resumen, no debe especificar otras etiquetas, como param o devuelve etiquetas.

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 con < (normalmente <summary>), se trata como un cuerpo de comentario con formato XML mediante etiquetas XML. Esta segunda manera le permite especificar notas independientes para un resumen corto, 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 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#.

Sintaxis de etiquetas	Descripción
`<summary>` *texto*`</summary>`	Especifica que el texto es una breve descripción del elemento de programa. La descripción suele ser una o dos oraciones.
`<remarks>` *texto*`</remarks>`	Especifica que el texto contiene información complementaria sobre el elemento del programa.
`<param name="`*nombre`">`descripción*`</param>`	Especifica el nombre y la descripción de una función o 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 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 como aparece en el archivo de documentación XML. Véase también los enlaces suelen aparecer 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. Esto 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="`*texto de referencia*`"></see>`	Especifica un vínculo en línea 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#. Sin embargo, un usuario puede definir sus propias etiquetas. Herramientas como fsdocs proporcionan compatibilidad con etiquetas adicionales, como <namespacedoc>. Las herramientas personalizadas o de generación de documentación interna también se pueden usar con las etiquetas estándar y se pueden admitir varios formatos de salida de HTML a PDF.

Comprobaciones en tiempo de compilación

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

Documentar constructos 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 elabora referencias cruzadas al estilo C# simples como cref="Console" para convertirlas en firmas XML completas y estos elementos no son comprobados por 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 se usa -warnon:3390.
El compilador de F#no comprueba los nombres usados en las etiquetas <typeparam> y <typeparamref>, incluso cuando se usa --warnon:3390.
No se proporcionan advertencias si falta documentación, incluso cuando se usa --warnon:3390.

Recomendaciones

Se recomienda documentar el código por muchas razones. A continuación se muestran algunos procedimientos recomendados, escenarios generales de casos de uso y aspectos que debe saber 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 garantizar que la documentación XML sea XML válida.
Considera agregar archivos de firma para separar los comentarios de documentación XML largos de tu implementación.
Por motivos de coherencia, se deben documentar todos los tipos visibles públicamente y sus miembros. Si tienes que hacerlo, hazlo todo.
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 debe escribirse con oraciones completas que terminen con paradas completas.

Compartir a través de