Partager via

Documenter votre code avec des commentaires XML

  • Article

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 type spécial 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é en même temps que votre assembly .NET afin que les IDE puissent utiliser des info-bulles pour afficher des informations rapides sur les types ou les membres. En outre, le fichier XML peut être exécuté via des outils tels que fsdocs pour générer des sites web de référence d’API.

Par défaut, les commentaires de documentation XML sont ignorés par le compilateur. Pour modifier ce paramètre, définissez --warnon:3390. Le compilateur vérifie ensuite la syntaxe du code XML et les paramètres référencés dans <param> et <paramref> balises.

Vous pouvez générer le fichier XML au moment de la compilation en effectuant l’une des opérations suivantes :

  • Vous pouvez ajouter un élément GenerateDocumentationFile à la section <PropertyGroup> de votre fichier projet .fsproj, 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 et 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 modifier 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 une <, l’intégralité du texte du commentaire est prise comme documentation récapitulative pour la construction de code qui suit immédiatement. Utilisez cette méthode lorsque vous souhaitez écrire uniquement un bref résumé pour chaque construction.

Le commentaire est encodé en XML pendant la préparation de la documentation, de sorte que les caractères tels que <, >et & ne doivent pas être échappés. Si vous ne spécifiez pas explicitement une balise récapitulative, vous ne devez pas spécifier d’autres balises, telles que param ou retourne balises.

L’exemple suivant montre la méthode alternative, sans balises XML. Dans cet exemple, le texte entier du commentaire 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 un corps de commentaire commence par < (normalement <summary>), il est traité comme un corps de commentaire au format XML à l’aide de balises XML. Cette deuxième façon vous permet de spécifier des notes distinctes pour un résumé court, des remarques supplémentaires, de la documentation pour chaque paramètre et paramètre 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

Si vous utilisez des balises XML, le tableau suivant décrit les balises externes reconnues dans les commentaires de code XML 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 est généralement une ou deux phrases.
<remarks> texte</remarks> Spécifie que le texte contient des informations supplémentaires sur l'élément du programme.
<param name=" nom">description</param> Spécifie le nom et la description d’une fonction ou d’un paramètre 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 texte décrit la valeur de retour d’une fonction ou d’une méthode.
<exception cref=" type">description</exception> Spécifie le type d’exception qui peut être généré 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 est le nom tel qu’il apparaît dans le fichier de documentation XML. Consultez également les liens généralement affichés en bas d’une page de documentation.

Le tableau suivant décrit les balises à utiliser dans les sections de description :

Syntaxe des balises Description
<para> texte</para> Spécifie un paragraphe de texte. Cela est utilisé pour séparer le texte à l'intérieur de la balise remarques.
<code> texte</code> Spécifie que le texte consiste en plusieurs lignes de code. Cette balise peut être utilisée par les générateurs de documentation pour afficher du texte dans une police appropriée pour le 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 appropriée pour le code.
<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 apparaît dans le fichier de documentation XML. Le texte est le texte affiché dans le lien.

Balises définies par l’utilisateur

Les balises précédentes représentent celles qui sont reconnues par le compilateur F# et les outils d’éditeur F# classiques. Toutefois, un utilisateur est libre de définir ses propres balises. Les outils comme fsdocs prennent en charge des balises supplémentaires comme <namespacedoc>. Les 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 de HTML à PDF peuvent être pris en charge.

Vérification au moment de la compilation

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

Documentation des constructions F#

Les constructions F# telles que les modules, les membres, les cas d’union et les champs d’enregistrement sont documentées par un commentaire /// immédiatement avant leur déclaration. Si nécessaire, les constructeurs implicites de classes sont documentés en donnant 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

Limitations

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

  • Dans 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 de style C#simple telles que 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 par traitement ultérieur, mais les signatures complètes doivent être utilisées.

  • Les balises <include>, <inheritdoc> ne sont pas prises en charge par le compilateur F#. Aucune erreur n’est donnée si elles sont utilisées, mais elles sont simplement copiées dans le fichier de documentation généré sans affecter la documentation générée.

  • Les références croisées ne sont pas vérifiées par le compilateur F#, même lorsque -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ée.

Recommandations

La documentation du code est recommandée pour de nombreuses raisons. Voici quelques bonnes pratiques, scénarios de cas d’usage généraux et éléments que vous devez savoir lors de l’utilisation de 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 commentaires de documentation XML longs 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 tout.

  • Au minimum, les modules, les types et leurs membres doivent avoir un commentaire /// simple ou une balise <summary>. 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 des arrêts complets.

Voir aussi