Documentación XML (F#)
En F#, se puede generar documentación a partir de comentarios de código de barra diagonal triple (///). Los comentarios XML pueden preceder a las declaraciones en archivos de código (.fs) o archivos de signatura (.fsi).
Generar documentación a partir de los comentarios
La compatibilidad de F# con la generación de documentación a partir de comentarios es la misma que en los demás lenguajes .NET Framework. Al igual que en los demás lenguajes .NET Framework, la opción del compilador -doc permite crear un archivo XML que contiene información que se puede convertir en documentación mediante una herramienta como Sandcastle. La documentación que se genera con herramientas diseñadas para ensamblados escritos en otros lenguajes .NET Framework suele dar lugar a una vista de las API que se basa en el formato compilado de las construcciones de F#. A menos que las herramientas admitan específicamente F#, la documentación generada por estas herramientas no tiene la vista de API de F#.
Para obtener más información sobre cómo generar documentación a partir de XML, vea Comentarios de documentación XML (Guía de programación de C#).
Etiquetas recomendadas
Existen dos mecanismos para escribir comentarios en la documentación XML. Uno consiste simplemente en escribir la documentación directamente en un comentario de barra diagonal triple sin usar etiquetas XML. De este modo, el texto del comentario se toma como documentación de resumen para la construcción de código que figura inmediatamente después. Use este método cuando solo desee escribir un breve resumen de cada construcción. El otro método consiste en utilizar etiquetas XML para proporcionar una documentación más estructurada. Este método permite especificar notas independientes para un breve resumen, observaciones adicionales, la documentación de cada parámetro, parámetro de tipo y excepciones desencadenadas, así como una descripción del valor devuelto. En la siguiente tabla, se describen las etiquetas XML que se reconocen en los comentarios de código XML de F#.
Sintaxis de la etiqueta |
Descripción |
|---|---|
<c> texto </c> |
Especifica que el texto es código. Esta etiqueta la pueden utilizar los generadores de documentación para mostrar el texto en una fuente apropiada para código. |
<summary> texto </summary> |
Especifica que el texto es una breve descripción de un elemento del programa. La descripción suele constar de una o dos frases. |
<remarks> texto </remarks> |
Especifica que el texto contiene información complementaria sobre un elemento del programa. |
<param name="nombre"> descripción </param> |
Especifica el nombre y la descripción de un parámetro de función o 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 un 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. |
<see cref="referencia"> texto </see> |
Especifica un vínculo insertado a otro elemento del 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. |
<seealso cref="Referencia ."/> |
Especifica un vínculoVea 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. Los vínculos Vea también suelen aparecer en la parte inferior de una página de documentación. |
<para> texto </para> |
Especifica un párrafo de texto. Se utiliza para separar texto dentro de la etiqueta remarks. |
Ejemplo
Descripción
A continuación figura un típico comentario de documentación XML en un archivo de signatura.
Código
/// <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
Ejemplo
Descripción
En el siguiente ejemplo, se muestra el método alternativa, sin etiquetas XML. En este ejemplo, se considera que todo el texto del comentario es un resumen. Tenga en cuenta que si no especifica explícitamente una etiqueta de resumen, no debe especificar otras etiquetas, como param o returns.
Código
/// 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