Documenter votre code avec XML (Visual Basic)

  • Article

Dans Visual Basic, vous pouvez documenter votre code à l’aide de XML.

Commentaires sur la documentation XML

Visual Basic fournit un moyen simple de créer automatiquement une documentation XML pour les projets. Vous pouvez générer automatiquement un squelette XML pour vos types et membres, puis fournir des résumés, une documentation descriptive pour chaque paramètre et d’autres remarques. Avec la configuration appropriée, la documentation XML est automatiquement émise dans un fichier XML portant le même nom de fichier racine que votre projet. Pour plus d’informations sur la configuration de la génération du fichier de documentation XML, consultez l’option de compilateur -doc et la propriété MSBuild GenerateDocumentationFile.

Le fichier XML peut être consommé ou manipulé au format XML. Ce fichier se trouve dans le même répertoire que le fichier .exe de sortie ou .dll de votre projet.

Le début de la documentation XML est symbolisé par '''. Le traitement de ces commentaires présente certaines restrictions :

  • La documentation doit être dans un format XML correct. Si le XML n’est pas correct, un avertissement est généré. En outre, un commentaire indiquant qu’une erreur s’est produite est ajouté au fichier de documentation.

  • Les développeurs sont libres de créer leur propre jeu de balises. Il est recommandé d’utiliser un ensemble de balises (voir Balises de commentaire XML). Certaines des balises recommandées ont des significations spéciales :

    • La balise <param> est utilisée pour décrire les paramètres. Quand elle est utilisée, le compilateur vérifie que le paramètre existe et que tous les paramètres sont décrits dans la documentation. Si la vérification échoue, le compilateur émet un avertissement.

    • L’attribut cref peut être joint à n’importe quelle balise pour fournir une référence à un élément de code. Le compilateur vérifie l’existence de cet élément de code. Si la vérification échoue, le compilateur émet un avertissement. Le compilateur respecte toutes les instructions Imports lorsqu’il recherche un type décrit dans l’attribut cref.

    • La balise <summary> est utilisée par IntelliSense dans Visual Studio pour afficher des informations supplémentaires sur un type ou un membre.

Pour plus d’informations sur la création d’un fichier .xml avec des commentaires de documentation, consultez les rubriques suivantes :

Voir aussi