Documenter votre code avec des commentaires XML

Article
03/09/2023

Vous pouvez produire de la documentation à partir de commentaires de code à triple barre oblique (///) en F#. Les commentaires XML peuvent précéder les déclarations dans les fichiers de code (.fs) ou les fichiers de signature (.fsi).

Les commentaires de documentation XML sont un genre particulier de commentaire, ajouté au-dessus de la définition d’un type ou d’un membre défini par l’utilisateur. Ils sont spéciaux, car ils peuvent être traités par le compilateur pour générer un fichier de documentation XML au moment de la compilation. Le fichier XML généré par le compilateur peut être distribué avec votre assembly .NET pour permettre aux IDE d’utiliser des info-bulles afin d’afficher des informations rapides concernant les types ou les membres. De plus, le fichier XML peut être exécuté par l’intermédiaire d’outils tels que fsdocs pour générer des sites web de références d’API.

Les commentaires de documentation XML, comme tous les autres commentaires, sont ignorés par le compilateur, sauf si les options décrites ci-dessous sont activées pour vérifier la validité et la complétude des commentaires au moment de la compilation.

Vous pouvez générer le fichier XML au moment de la compilation en procédant comme suit :

Vous pouvez ajouter un élément GenerateDocumentationFile à la section <PropertyGroup> de votre fichier projet .fsproj, ce qui génère un fichier XML dans le répertoire du projet avec le même nom de fichier racine que l’assembly. Par exemple :
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Pour plus d’informations, consultez la propriété GenerateDocumentationFile.
Si vous développez une application à l’aide de Visual Studio, cliquez avec le bouton droit sur le projet, puis sélectionnez Propriétés. Dans la boîte de dialogue des propriétés, sélectionnez l’onglet Générer, puis cochez Fichier de documentation XML. Vous pouvez également changer l’emplacement dans lequel le compilateur écrit le fichier.

Il existe deux façons d’écrire des commentaires de documentation XML : avec et sans balises XML. Ces deux méthodes utilisent des commentaires à triple barre oblique.

Commentaires sans balises XML

Si un commentaire /// ne commence pas par <, le texte du commentaire dans son intégralité est considéré comme le résumé de la construction de code qui suit. Utilisez cette méthode quand vous souhaitez écrire un bref résumé pour chaque construction.

Le commentaire étant encodé en XML pendant la préparation de la documentation, les caractères tels que <, > et & n’ont pas besoin d’être placés dans une séquence d’échappement. Si vous ne spécifiez pas explicitement de balise de résumé, n’utilisez pas d’autres balises comme param ou returns.

L’exemple suivant montre la méthode alternative, sans balises XML. Dans cet exemple, le texte du commentaire dans son intégralité est considéré comme un résumé.

/// 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

Commentaires avec des balises XML

Si le corps d’un commentaire commence par < (normalement <summary>), il est traité comme un corps de commentaire au format XML avec des balises XML. Cette deuxième méthode vous permet de spécifier des notes distinctes pour un bref résumé, des remarques supplémentaires, de la documentation pour les paramètres, paramètres de type et exceptions levées, ainsi qu’une description de la valeur de retour.

Voici un commentaire de documentation XML classique dans un fichier de signature :

/// <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

Balises recommandées

Si vous utilisez des balises XML, le tableau suivant décrit les balises externes reconnues dans les commentaires de code XML en F#.

Syntaxe des balises	Description
`<summary>`*texte*`</summary>`	Spécifie que le texte est une brève description de l’élément de programme. La description comprend généralement une ou deux phrases.
`<remarks>`*texte*`</remarks>`	Spécifie que le texte contient des informations supplémentaires sur l’élément de programme.
`<param name="`*nom`">`description*`</param>`	Spécifie le nom et la description d’un paramètre de fonction ou de méthode.
`<typeparam name="`*nom`">`description*`</typeparam>`	Spécifie le nom et la description d’un paramètre de type.
`<returns>`*texte*`</returns>`	Spécifie que le texte décrit la valeur de retour d’une fonction ou d’une méthode.
`<exception cref="`*type`">`description*`</exception>`	Spécifie le type de l’exception qui peut être générée et les circonstances dans lesquelles elle est levée.
`<seealso cref="`*référence*`"/>`	Spécifie un lien Voir aussi vers la documentation sur un autre type. La référence correspond au nom tel qu’il apparaît dans le fichier de documentation XML. Les liens Voir aussi apparaissent généralement en bas d’une page de documentation.

Le tableau suivant décrit les balises à utiliser à l’intérieur des sections de description :

Syntaxe des balises	Description
`<para>`*texte*`</para>`	Spécifie un paragraphe de texte. Cela permet de séparer le texte à l’intérieur de la balise remarks.
`<code>`*texte*`</code>`	Spécifie que le texte comprend plusieurs lignes de code. Cette balise peut être utilisée par les générateurs de documentation pour afficher du texte dans une police adaptée au code.
`<paramref name="`*nom*`"/>`	Spécifie une référence à un paramètre dans le même commentaire de documentation.
`<typeparamref name="`*nom*`"/>`	Spécifie une référence à un paramètre de type dans le même commentaire de documentation.
`<c>`*texte*`</c>`	Spécifie que le texte correspond à du code inline. Cette balise peut être utilisée par les générateurs de documentation pour afficher du texte dans une police adaptée au code.
`<see cref="`*référence`">`texte*`</see>`	Spécifie un lien inline vers un autre élément de programme. La référence correspond au nom tel qu’il apparaît dans le fichier de documentation XML. Le texte correspond au texte affiché dans le lien.

Balises définies par l’utilisateur

Les balises précédentes sont reconnues par le compilateur F# et les outils d’édition de code F# classiques. Toutefois, un utilisateur est libre de définir ses propres balises. Des outils tels que fsdocs prennent en charge d’autres balises comme <namespacedoc>. Des outils de génération de documentation personnalisés ou internes peuvent également être utilisés avec les balises standard, et plusieurs formats de sortie, du format HTML au format PDF, peuvent être pris en charge.

Vérifications au moment de la compilation

Quand --warnon:3390 est activé, le compilateur vérifie la syntaxe du XML et les paramètres référencés dans les balises <param> et <paramref>.

Documentation des constructions F#

Les constructions F# comme les modules, les membres, les cas d’union et les champs d’enregistrement sont documentées par un commentaire /// juste avant leur déclaration. Si nécessaire, vous pouvez documenter des constructeurs implicites en ajoutant un commentaire /// avant la liste d’arguments. Par exemple :

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

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

Limites

Certaines fonctionnalités de la documentation XML en C# et dans d’autres langages .NET ne sont pas prises en charge en F#.

En F#, les références croisées doivent utiliser la signature XML complète du symbole correspondant, par exemple cref="T:System.Console". Les références croisées simples de style C# comme cref="Console" ne sont pas élaborées en signatures XML complètes, et ces éléments ne sont pas vérifiés par le compilateur F#. Certains outils de documentation peuvent autoriser l’utilisation de ces références croisées pour un traitement ultérieur, mais les signatures complètes doivent être utilisées.
Les balises <include> et <inheritdoc> ne sont pas prises en charge par le compilateur F#. Aucune erreur n’est affichée si vous les utilisez, mais elles sont simplement copiées dans le fichier de documentation généré sans affecter la documentation produite.
Les références croisées ne sont pas vérifiées par le compilateur F#, même quand -warnon:3390 est utilisé.
Les noms utilisés dans les balises <typeparam> et <typeparamref> ne sont pas vérifiés par le compilateur F#, même quand --warnon:3390 est utilisé.
Aucun avertissement n’est donné si la documentation est manquante, même quand --warnon:3390 est utilisé.

Recommandations

La documentation du code est recommandée pour de nombreuses raisons. Voici quelques bonnes pratiques, des scénarios de cas d’usage généraux et des éléments que vous devez connaître quand vous utilisez des balises de documentation XML dans votre code F#.

Activez l’option --warnon:3390 dans votre code pour vous assurer que votre documentation XML est valide.
Envisagez d’ajouter des fichiers de signature pour séparer les longs commentaires de documentation XML de votre implémentation.
Par souci de cohérence, tous les types visibles publiquement et leurs membres doivent être documentés. Si vous devez le faire, faites-le complètement.
Au minimum, les modules, les types et leurs membres doivent avoir un commentaire /// ou une balise <summary> simple. Le texte apparaîtra dans une fenêtre d’info-bulle d’autocomplétion dans les outils d’édition F#.
Le texte de la documentation doit être écrit à l’aide de phrases complètes se terminant par un point.