Commentaires de documentation XML

Remonter à Editeur de code

Présentation

Les commentaires de documentation XML sont :

• Introduits avec une triple barre oblique (///).
• Structurés à l'aide de balises XML.
• Pliés et dépliés comme une région ou un bloc de code normal (voir Utilisation du pliage de code).
• Supportés par Delphi.

Les commentaires de documentation XML sont affichés dans l'audit d'aide (s'ils sont analysés avec succès) et sont aussi inclus par le compilateur lors de la génération de la documentation XML (comme les éléments XML devnotes).

Les balises XML doivent être correctement fermées, par exemple <para>...</para>. Si un élément fermant n'est pas trouvé, la représentation XML est alors invalide et l'audit d'aide n'est pas capable d'afficher les commentaires XML.

Exemple d'une fonction Delphi avec des commentaires de documentation XML

 
 /// <summary> Removes the specified item from the collection
 /// </summary>
 /// <param name="Item">The item to remove
 /// </param>
 /// <param name="Collection">The group containing the item
 /// </param>
 /// <remarks>
 /// If parameter "Item" is null, an exception is raised.
 /// <see cref="EArgumentNilException" />
 /// </remarks>
 /// <returns>True if the specified item is successfully removed;
 /// otherwise False is returned.
 /// </returns>
 function RemoveItem(Item: Pointer; Collection: Pointer): Boolean;
 begin
   // Non-XML DOC comment
   // ...
 end;

Pour consulter d'autres exemples de commentaires de documentation XML, voir les fichiers source suivants :

• DSServer.pas
• DSCommonServer.pas
• DSHTTP.pas

Eléments XML

Vous pouvez utiliser les éléments suivants dans les commentaires de documentation XML :

<summary>

Un récapitulatif de la classe ou de la fonction cible

<para>

Un paragraphe

<c>

Texte dans une fonte de largeur fixe

<code>

Texte préformaté, tel que le code source

<remarks>

Remarques concernant la classe ou la fonction cible

<param name="ParameterName">

Le nom et la description d'un paramètre spécifique

<see>

Référence à un type, symbole ou identificateur spécifique

<returns>

Description de la valeur de retour de la fonction cible. Par exemple, la fonction peut renvoyer un code d'erreur.

<exception cref="EExceptionTypeName">

Exception qui peut être déclenchée par une méthode

<permission cref="PermissionType">

Permissions pour une méthode

Voir aussi

• Commentaires de documentation XML (Guide de programmation C#)
• Documentation XML pour le code C++ (documentation XML générée par le compilateur)
• Utilisation du pliage de code