<include> (guide de programmation C#)

Article
03/04/2013

<include file='filename' path='tagpath[@name="id"]' />

Paramètres

filename
Nom du fichier XML contenant la documentation.Le nom du fichier peut être précisé par un chemin.Mettez filename entre guillemets simples (' ').
tagpath
Chemin d'accès des balises dans filename qui permet d'accéder au name de la balise.Mettez le chemin entre guillemets simples (' ').
name
Dans la balise, spécificateur de nom précédant les commentaires ; name est associé à un id.
id
ID de la balise qui précède les commentaires.Placez l'ID entre guillemets doubles (" ").

Notes

La balise <include> permet de faire référence à des commentaires situés dans un autre fichier qui décrivent les types et membres dans votre code source.Cette solution remplace celle consistant à placer des commentaires de documentation directement dans votre fichier de code source.En mettant la documentation dans un fichier séparé, vous pouvez appliquer séparément le contrôle de code source à la documentation du code source.Une personne peut avoir le fichier de code source extrait et une autre peut avoir le fichier de documentation extrait.

La balise <include> utilise la syntaxe XML XPath.Pour en savoir plus sur les différentes façons de personnaliser votre utilisation de <include>, consultez la documentation XPath.

Exemple

Cet exemple fait appel à plusieurs fichiers.Le premier, qui utilise <include>, est indiqué ci-dessous :

// compile with: /doc:DocFileName.xml 

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

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

Le deuxième fichier, xml_include_tag.doc, contient les 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

La sortie suivante est générée lorsque vous compilez les classes Test2 et Test avec la ligne de commande suivante : /doc:DocFileName.xml. Dans Visual Studio, vous spécifiez l'option de commentaires de document XML dans le volet Génération du Concepteur de projets.Lorsque le compilateur C# rencontre la balise < inclue >, il recherchera des commentaires sur la documentation dans xml_include_tag.doc au lieu du fichier source actif.Le compilateur génère ensuite DocFileName.xml et c'est le fichier qui est consommé par les outils de documentation tels que Sandcastle pour produire la documentation finale.

<?xml version="1.0"?> 
<doc> 
    <assembly> 
        <name>xml_include_tag</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

Référence

Balises recommandées pour commentaires de documentation (Guide de programmation C#)

Concepts

Guide de programmation C#

Partager via