Partager via

<include> balise de documentation

  • Article

La balise <include> vous permet de faire référence à des commentaires dans un autre fichier qui décrivent les types et les membres dans votre code source. Cette balise est une alternative au placement de commentaires de documentation directement dans votre fichier de code source. Par exemple, vous pouvez utiliser <include> pour insérer des commentaires standard « réutilisables » utilisés dans toute votre équipe ou entreprise.

Syntaxe

/// <include file='filename' path='tag-path[@name="ID"' />

Paramètres

filename
Nom du fichier contenant la documentation. Le nom de fichier peut être qualifié avec un chemin. Mettez le nom entre guillemets simples ou doubles. Le compilateur émet un avertissement s’il ne trouve filenamepas .

tag-path
Expression XPath valide qui sélectionne l’ensemble de nœuds souhaité contenu dans le fichier.

name
Spécificateur de nom contenu dans la balise qui précède les commentaires ; name possède un ID.

ID
ID de la balise qui précède les commentaires. Placez l’ID entre guillemets simples ou doubles.

Notes

La <include> balise utilise la syntaxe XPath XML. Reportez-vous à la documentation XPath pour savoir comment personnaliser l’utilisation <include>.

Compilez avec /doc pour traiter les commentaires de documentation dans un fichier.

Exemple

Cet exemple utilise plusieurs fichiers. Le premier fichier, qui utilise <include>, contient les commentaires de documentation suivants :

// xml_include_tag.cpp
// compile with: /clr /doc /LD
// post-build command: xdcmake xml_include_tag.dll

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
public ref class Test {
   void TestMethod() {
   }
};

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
public ref class Test2 {
   void Test() {
   }
};

Le deuxième fichier contient xml_include_tag.docles commentaires de documentation suivants :

<MyDocs>

<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>

<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>

</MyDocs>

Sortie du programme

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>t2</name>
    </assembly>
    <members>
        <member name="T:Test">
            <summary>
The summary for this type.
</summary>
        </member>
        <member name="T:Test2">
            <summary>
The summary for this other type.
</summary>
        </member>
    </members>
</doc>

Voir aussi

Documentation XML