Compartilhar via

Marca de documentação <include>

  • Artigo

A marca <include> permite consultar comentários em outro arquivo que descrevem os tipos e membros em seu código-fonte. Essa marca é uma alternativa para inserir comentários de documentação diretamente em seu arquivo de código-fonte. Por exemplo, use <include> para inserir comentários "clichê" padrão usados por toda a equipe ou empresa.

Sintaxe

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

Parâmetros

filename
O nome do arquivo que contém a documentação. O nome do arquivo pode ser qualificado com um caminho. Coloque o nome entre aspas simples ou duplas. O compilador emite um aviso se não encontrar filename.

tag-path
Uma expressão XPath válida que seleciona o conjunto de nós desejado contido no arquivo.

name
O especificador de nome na marca que precede os comentários; name terá um ID.

ID
A ID da marca que precede os comentários. Coloque o ID entre aspas simples ou duplas.

Comentários

A marca <include> usa a sintaxe XML XPath. Veja a documentação do XPath para descobrir outras formas de personalização usando <include>.

Compile com /doc para processar comentários de documentação em um arquivo.

Exemplo

Este exemplo usa vários arquivos. O primeiro arquivo, que usa <include>, contém os seguintes comentários da documentação:

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

O segundo arquivo, xml_include_tag.doc, contém os seguintes comentários da documentação:

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

Saída do 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>

Confira também

Documentação XML