Skip to main content

Comentários /// | Summary | Documentação em CSharp | CSharp

  • Comentários /// | Summary | Documentação em CSharp | CSharp

No C#, o /// é usado para criar comentários XML que geram documentação automática para o código. Esses comentários são importantes para fornecer informações adicionais sobre o comportamento de classes, métodos, propriedades, etc. Eles podem ser usados para gerar documentação que pode ser consumida por ferramentas como o Visual Studio ou outras ferramentas de geração de documentação.

Aqui estão as possibilidades de documentação que você pode usar com o /// no C#:

1. Resumo (<summary>)​

O elemento <summary> é usado para descrever de forma breve o que uma classe, método, propriedade ou outro membro faz.

/// <summary>
/// Este método soma dois números inteiros.
/// </summary>
public int Somar(int a, int b)
{
    return a + b;
}

2. Parâmetros (<param>)​

O elemento <param> é utilizado para descrever um parâmetro de um método, indicando seu nome e o que ele representa.

/// <summary>
/// Este método soma dois números inteiros.
/// </summary>
/// <param name="a">O primeiro número a ser somado.</param>
/// <param name="b">O segundo número a ser somado.</param>
public int Somar(int a, int b)
{
    return a + b;
}

3. Valor de Retorno (<returns>)​

O elemento <returns> é utilizado para descrever o valor de retorno de um método.

/// <summary>
/// Este método soma dois números inteiros.
/// </summary>
/// <param name="a">O primeiro número a ser somado.</param>
/// <param name="b">O segundo número a ser somado.</param>
/// <returns>O resultado da soma de `a` e `b`.</returns>
public int Somar(int a, int b)
{
    return a + b;
}

4. Exceções (<exception>)​

O elemento <exception> descreve quais exceções o método pode lançar.

/// <summary>
/// Este método divide dois números.
/// </summary>
/// <param name="dividendo">O número a ser dividido.</param>
/// <param name="divisor">O número pelo qual o dividendo será dividido.</param>
/// <returns>O resultado da divisão.</returns>
/// <exception cref="DivideByZeroException">Lançada se o divisor for zero.</exception>
public double Dividir(double dividendo, double divisor)
{
    if (divisor == 0)
        throw new DivideByZeroException("Não é possível dividir por zero.");
    
    return dividendo / divisor;
}

5. Notas de Obsoleto ([Obsolete])​

/// <summary>
/// [OBSOLETA] Esta classe foi criada incorretamente fora da camada adequada.
/// Responsável por configurar conexões AMQP, sua responsabilidade pertence à camada de Infra.
/// </summary>
/// <remarks>
/// MOTIVO: Viola a separação de responsabilidades da arquitetura. Criada originalmente na camada errada.
/// AÇÃO RECOMENDADA: Utilize <see cref="Infra.Data.Context.RabbitMQContext"/> para configuração de conexões AMQP.
/// Para publicação de mensagens, utilize <see cref="Infra.Data.MessagingRabbitMQ.RabbitEventPublisher"/>.
/// STATUS: Classe mantida temporariamente por questões de compatibilidade.
/// DATA: 2025-12-22
/// </remarks>

[Obsolete("Use NovaClasse em vez desta.", error: false)]
public void FuncaoAntiga()
{
    // Lógica do método
}

6. Tópicos de Código (<code>)​

Você pode usar o elemento <code> para inserir trechos de código diretamente na documentação XML.

/// <summary>
/// Exemplo de código:
/// <code>
/// int resultado = Somar(2, 3);
/// Console.WriteLine(resultado);
/// </code>
/// </summary>
public int Somar(int a, int b)
{
    return a + b;
}

7. Notas sobre a Disponibilidade (<remarks>)​

O elemento <remarks> pode ser usado para fornecer mais detalhes sobre um método, classe ou propriedade, além de um resumo.

/// <summary>
/// Este método soma dois números.
/// </summary>
/// <remarks>
/// Este método deve ser usado apenas com números inteiros.
/// </remarks>
public int Somar(int a, int b)
{
    return a + b;
}

8. Exemplo (<example>)​

O elemento <example> pode ser usado para fornecer um exemplo de como utilizar um determinado método ou classe.

/// <summary>
/// Este método soma dois números inteiros.
/// </summary>
/// <example>
/// O seguinte exemplo mostra como usar o método Somar:
/// <code>
/// int resultado = Somar(3, 4);
/// Console.WriteLine(resultado);  // Exibe: 7
/// </code>
/// </example>
public int Somar(int a, int b)
{
    return a + b;
}

9. Informações sobre a Autoría (<author>)​

Embora não seja um elemento obrigatório, você pode adicionar informações sobre o autor utilizando o elemento <author>.

/// <summary>
/// Este método soma dois números inteiros.
/// </summary>
/// <author>João Silva</author>
public int Somar(int a, int b)
{
    return a + b;
}

10. Grupo de Tipos (<typeparam>)​

Usado para documentar parâmetros de tipo em métodos genéricos.

/// <summary>
/// Este método soma dois valores genéricos.
/// </summary>
/// <typeparam name="T">O tipo dos valores a serem somados.</typeparam>
/// <param name="a">O primeiro valor a ser somado.</param>
/// <param name="b">O segundo valor a ser somado.</param>
/// <returns>O resultado da soma.</returns>
public T Somar<T>(T a, T b)
{
    dynamic valor1 = a;
    dynamic valor2 = b;
    return valor1 + valor2;
}

11. Referência (<see> e <seealso>)​

Você pode usar <see> para referenciar um tipo, método ou membro de código diretamente na documentação, e o <seealso> para adicionar links para documentos ou outras referências.

/// <summary>
/// Este método divide dois números.
/// </summary>
/// <seealso cref="Multiplicar"/>
public double Dividir(double dividendo, double divisor)
{
    return dividendo / divisor;
}

12. Comentário Inline (<see cref="..."/>)​

O elemento <see cref="..."/> pode ser usado dentro de um comentário para criar links diretamente para um membro específico do código.

/// <summary>
/// Este método faz uma multiplicação. Veja também <see cref="Dividir"/>.
/// </summary>
public double Multiplicar(double a, double b)
{
    return a * b;
}

Exemplo Completo​

Aqui está um exemplo completo de documentação XML para um método no C# usando todas as diretrizes acima:

/// <summary>
/// Este método realiza uma operação matemática de soma entre dois números.
/// </summary>
/// <param name="a">O primeiro número a ser somado.</param>
/// <param name="b">O segundo número a ser somado.</param>
/// <returns>O resultado da soma entre <paramref name="a"/> e <paramref name="b"/>.</returns>
/// <exception cref="ArgumentException">Lançada quando algum parâmetro é menor que zero.</exception>
/// <remarks>
/// Este método só deve ser utilizado com números inteiros não negativos.
/// </remarks>
/// <example>
/// O seguinte exemplo mostra como usar o método Somar:
/// <code>
/// int resultado = Somar(5, 3);
/// Console.WriteLine(resultado);  // Exibe 8
/// </code>
/// </example>
/// <author>João Silva</author>
/// <seealso cref="Subtrair"/>
public int Somar(int a, int b)
{
    if (a < 0 || b < 0)
    {
        throw new ArgumentException("Os números não podem ser negativos.");
    }
    return a + b;
}

Resumo:​

  • <summary>: Descrição geral do que o método faz.
  • <param>: Descrição dos parâmetros do método.
  • <returns>: Descrição do que o método retorna.
  • <exception>: Descrição de exceções que o método pode lançar.
  • <remarks>: Detalhes adicionais sobre o método.
  • <example>: Exemplos de como usar o método.
  • <author>: Informações sobre o autor.
  • <seealso>: Links para outros métodos ou classes relacionadas.
  • <typeparam>: Para métodos genéricos.
  • <code> e <see>: Para mostrar exemplos e links para membros de código.

Esses comentários ajudam a gerar documentação automática, o que facilita a compreensão do código por outros desenvolvedores e ferramentas.