Como: Use os recursos de documentação XML (guia de programação translation from VPE for Csharp)

O exemplo a seguir fornece uma visão geral básica de um tipo que foi documentado.

Exemplo

// compile with: /doc:DocFileName.xml 

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member 
/// through the remarks tag</remarks>
public class TestClass
{
    /// <summary>
    /// Store for the name property</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here
    }

    /// <summary>
    /// Name property </summary>
    /// <value>
    /// A value tag is used to describe the property value</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here
        return 0;
    }
}

// This .xml file was generated with the previous code sample. <?xml version="1.0"?> <doc>     <assembly>         <name>xmlsample</name>     </assembly>     <members>         <member name="T:SomeClass">             <summary>             Class level summary documentation goes here.</summary>             <remarks>             Longer comments can be associated with a type or member              through the remarks tag</remarks>         </member>         <member name="F:SomeClass.m_Name">             <summary>             Store for the name property</summary>         </member>         <member name="M:SomeClass.#ctor">             <summary>The class constructor.</summary>          </member>         <member name="M:SomeClass.SomeMethod(System.String)">             <summary>             Description for SomeMethod.</summary>             <param name="s"> Parameter description for s goes here</param>             <seealso cref="T:System.String">             You can use the cref attribute on any tag to reference a type or member              and the compiler will check that the reference exists. </seealso>         </member>         <member name="M:SomeClass.SomeOtherMethod">             <summary>             Some other method. </summary>             <returns>             Return results are described through the returns tag.</returns>             <seealso cref="M:SomeClass.SomeMethod(System.String)">             Notice the use of the cref attribute to reference a specific method </seealso>         </member>         <member name="M:SomeClass.Main(System.String[])">             <summary>             The entry point for the application.             </summary>             <param name="args"> A list of command line arguments</param>         </member>         <member name="P:SomeClass.Name">             <summary>             Name property </summary>             <value>             A value tag is used to describe the property value</value>         </member>     </members> </doc>

Compilando o código

Para compilar o exemplo, digite a seguinte linha de comando:

csc XMLsample.cs /doc:XMLsample.xml

Este será criar o arquivo XML XMLsample.xml, que você pode ver no seu navegador ou usando o comando TYPE.

Programação robusta

Documentação XML começa com / / /.Quando você cria um novo projeto, os assistentes colocar algumas linhas / / / starter para você.O processamento desses comentários tem algumas restrições:

• A documentação deve ser XML bem formado.Se não for o XML bem formado, um aviso é gerado e o arquivo de documentação conterá um comentário dizendo que ocorreu um erro.

• Os desenvolvedores estão livres para criar seu próprio conjunto de marcas.Há um conjunto recomendado de Rótulos (consulte a seção de leitura adicional).Algumas das marcas recomendadas têm significado especial:

  • A marca <param> é usada para descrever os parâmetros.Se usado, o compilador verificará se o parâmetro existe e que todos os parâmetros estão descritos na documentação.Se a verificação falhou, o compilador emitirá um aviso.

  • O atributo cref pode ser anexado a qualquer marca para fornecer uma referência a um elemento de código.O compilador verificar a existência desse elemento de código.Se a verificação falhou, o compilador emitirá um aviso.O compilador respeita qualquer using instruções quando procura um tipo descrito o cref atributo.

  • A marca <resumo>é usada pelo IntelliSense no Visual Studio para exibir informações adicionais sobre um tipo ou membro.

    Observação:
    O arquivo XML não fornece informações completas sobre o tipo e membros (por exemplo, ele não contém qualquer informação de tipo).Para obter informações completas sobre um tipo ou membro, o arquivo de documentação deve ser usado juntamente com reflexão no tipo real ou membro.

Consulte também

Tarefas

Exemplo de documentação XML

Conceitos

Guia de Programação C#

Referência

/doc (processo Documentação Comments) (opções do compilador de C#)

Comentários de documentação XML (Guia de programação C#)