Etiqueta de documentación <include>

La etiqueta <include> le permite hacer referencia a comentarios colocados en otro archivo que describen los tipos y miembros en el código fuente. Esta etiqueta es una alternativa a colocar los comentarios de documentación directamente en el archivo de código fuente. Por ejemplo, se puede usar <include> para insertar comentarios estándar "reutilizables" que se usen en todo el equipo o la empresa.

Sintaxis

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

Parámetros

filename
El nombre del archivo que contiene la documentación. El nombre de archivo se puede calificar con una ruta de acceso. Ponga el nombre entre comillas simples o dobles. El compilador emite una advertencia si no encuentra filename.

tag-path
Una expresión XPath válida que selecciona el conjunto de nodos deseado que se encuentra en el archivo.

name
El especificador de nombre en la etiqueta que precede a los comentarios; name tendrá un ID.

ID
El identificador de la etiqueta que precede a los comentarios. Ponga el id. entre comillas simples o dobles.

Comentarios

La etiqueta <include> usa la sintaxis de XPath de XML. Consulte la documentación de XPath para ver formas de personalización mediante <include>.

Compile con /doc para procesar los comentarios de documentación a un archivo.

Ejemplo

En este ejemplo se usan múltiples archivos. El primer archivo, en el que se usa <include>, contiene los comentarios de documentación siguientes:

// 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() {
   }
};

El segundo archivo, xml_include_tag.doc, contiene los comentarios de documentación siguientes:

<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>

Resultados del programa

<?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>

Consulte también

Documentación de XML