Documentation XML (F#)
En F#, vous pouvez produire de la documentation à partir des commentaires de code introduits par une triple barre oblique (///). Des commentaires XML peuvent précéder les déclarations dans les fichiers de code (.fs) ou les fichiers de signature (.fsi).
Génération de documentation à partir de commentaires
En F#, la prise en charge de la génération de documentation à partir de commentaires est la même que dans d'autres langages .NET Framework. Ainsi, l'option de compilateur -doc vous permet de produire un fichier XML qui contient des informations pouvant être converties en documentation à l'aide d'un outil tel que Sandcastle. La documentation générée à l'aide d'outils conçus pour une utilisation avec les assemblys écrits dans d'autres langages .NET Framework produit en général une vue des API basée sur la forme compilée des constructions F#. À moins que les outils ne prennent en charge le langage F# spécifiquement, la documentation générée par ces outils ne correspond pas à la vue F# d'une API.
Pour plus d'informations sur la génération de documentation à partir de XML, consultez Commentaires de documentation XML (Guide de programmation C#).
Balises recommandées
Il existe deux façons d'écrire des commentaires sur la documentation XML. La première consiste à écrire directement la documentation dans un commentaire introduit par une triple barre oblique, sans utiliser de balise XML. Si vous procédez ainsi, le texte de commentaire entier est pris comme documentation de résumé pour la construction de code qui vient immédiatement après. Utilisez cette méthode lorsque vous souhaitez écrire seulement un court récapitulatif pour chaque construction. L'autre méthode consiste à utiliser des balises XML pour fournir une documentation plus structurée. La seconde méthode vous permet de spécifier des remarques séparées pour un résumé court, des notes supplémentaires, de la documentation pour chaque paramètre, paramètre de type et exception levée, et une description de la valeur de retour. Le tableau suivant décrit les balises XML reconnues dans les commentaires de code XML F#.
Syntaxe de balises |
Description |
|---|---|
<c> texte </c> |
Spécifie que texte est du code. Cette balise peut être utilisée par les générateurs de documentation pour afficher du texte dans une police appropriée pour du code. |
<summary> texte </summary> |
Spécifie que texte est une brève description de l'élément de programme. La description est habituellement d'une ou deux phrases. |
<remarks> texte </remarks> |
Spécifie que texte contient des informations supplémentaires à propos de l'élément de programme. |
<param name="nom"> description </param> |
Spécifie le nom et la description pour une fonction ou un paramètre de méthode. |
<typeparam name="nom"> description </typeparam> |
Spécifie le nom et la description pour un paramètre de type. |
<returns> texte </returns> |
Spécifie que texte décrit la valeur de retour d'une fonction ou méthode. |
<exception cref="type"> description </exception> |
Spécifie le type d'exception qui peut être généré et les circonstances dans lesquelles cette exception est levée. |
<see cref="référence"> texte </see> |
Spécifie un lien inline vers un autre élément de programme. La référence est le nom tel qu'il s'affiche dans le fichier de documentation XML. Le texte est le texte affiché dans le lien. |
<seealso cref="Référence "/> |
Spécifie un lien « Voir aussi » vers la documentation pour un autre type. La référence est le nom tel qu'il s'affiche dans le fichier de documentation XML. Les liens « Voir aussi » apparaissent habituellement au bas d'une page de documentation. |
<para> texte </para> |
Spécifie un paragraphe de texte. Syntaxe utilisée pour séparer le texte à l'intérieur de la balise remarks. |
Exemple
Description
Voici un commentaire typique sur la documentation XML dans un fichier de signature.
Code
/// <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
Exemple
Description
L'exemple suivant illustre la méthode alternative sans balise XML. Dans cet exemple, le texte entier du commentaire est considéré comme un résumé. Notez que si vous ne spécifiez pas explicitement de balise de résumé, vous ne devez pas spécifier d'autres balises, telles que les balises param ou returns.
Code
/// 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