Como usar os recursos da documentação XML (Guia de Programação em C#)

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

Exemplo

// If compiling from the command line, compile with: /doc:YourFileName.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 : TestInterface
{
    /// <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;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <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;
    }
}

/// <summary> 
/// Documentation that describes the interface goes here. 
/// </summary> 
/// <remarks> 
/// Details about the interface go here. 
/// </remarks> 
interface TestInterface
{
    /// <summary> 
    /// Documentation that describes the method goes here. 
    /// </summary> 
    /// <param name="n">
    /// Parameter n requires an integer argument. 
    /// </param> 
    /// <returns> 
    /// The method returns an integer. 
    /// </returns> 
    int InterfaceMethod(int n);
}

Compilando o código

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

csc XMLsample.cs /doc:XMLsample.xml

Isso 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 o XML não está 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 tags (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 irá verificar se esse elemento de código existe. Se a verificação falhou, o compilador emitirá um aviso. O compilador respeita qualquer using instruções ao procurar por um tipo descrito o cref atributo.

  • O <summary> marca é usada pelo IntelliSense dentro de Visual Studio para exibir informações adicionais sobre um tipo ou membro.

    Dica

    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 em conjunto com uma reflexão sobre o tipo real ou membro.

Consulte também

Referência

/doc (opções do compilador C#)

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

Conceitos

Guia de Programação em C#