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

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

---

O que é <inheritdoc>

<inheritdoc> é uma tag de documentação XML do C# utilizada para herdar automaticamente a documentação de outro membro (classe, método, propriedade ou interface).

Essa tag evita duplicação de comentários e mantém a documentação consistente entre interfaces, classes base e implementações concretas.

Ela é muito usada em:

• Implementações de interfaces
• Métodos override
• Bibliotecas e SDKs
• APIs públicas
• Frameworks

---

Estrutura básica

A tag é usada dentro de comentários XML:

/// <inheritdoc/>

Ela instrui ferramentas de documentação e o IntelliSense a copiar a documentação do membro base.

---

Exemplo sem <inheritdoc>

Quando um método implementa uma interface, normalmente seria necessário repetir a documentação.

public interface ICalculator
{
    /// <summary>
    /// Soma dois números.
    /// </summary>
    int Add(int a, int b);
}

public class Calculator : ICalculator
{
    /// <summary>
    /// Soma dois números.
    /// </summary>
    public int Add(int a, int b)
    {
        return a + b;
    }
}

Problema:

• duplicação de documentação
• manutenção mais difícil
• risco de inconsistência

---

Exemplo usando <inheritdoc>

Com inheritdoc, a documentação é herdada automaticamente.

public interface ICalculator
{
    /// <summary>
    /// Soma dois números.
    /// </summary>
    int Add(int a, int b);
}

public class Calculator : ICalculator
{
    /// <inheritdoc/>
    public int Add(int a, int b)
    {
        return a + b;
    }
}

Agora:

• IntelliSense exibirá a mesma descrição da interface
• não há duplicação de comentários

---

Herdando documentação de classes base

<inheritdoc> também funciona em métodos sobrescritos (override).

public abstract class Animal
{
    /// <summary>
    /// Emite o som do animal.
    /// </summary>
    public abstract void Speak();
}

public class Dog : Animal
{
    /// <inheritdoc/>
    public override void Speak()
    {
        Console.WriteLine("Woof");
    }
}

A documentação de Speak() será herdada da classe Animal.

---

Herdando documentação usando cref

Também é possível especificar explicitamente de qual membro a documentação será herdada.

/// <inheritdoc cref="ICalculator.Add"/>
public int Add(int a, int b)
{
    return a + b;
}

Explicação:

• cref significa code reference
• indica exatamente qual membro contém a documentação original

---

Uso comum em bibliotecas .NET

Frameworks .NET utilizam muito essa tag para evitar duplicação.

Exemplo típico:

/// <inheritdoc/>
public override string ToString()
{
    return base.ToString();
}

Outro exemplo com interface:

public class FileLogger : ILogger
{
    /// <inheritdoc/>
    public void Log(string message)
    {
        File.AppendAllText("log.txt", message);
    }
}

---

Integração com IntelliSense

Ferramentas que interpretam <inheritdoc>:

• Visual Studio
• Rider
• DocFX
• Sandcastle
• Geradores de documentação

Quando usada corretamente, a documentação herdada aparece automaticamente no IntelliSense.

Exemplo no editor:

Calculator.Add(int a, int b)

Soma dois números.

Mesmo sem duplicar o comentário.

---

Benefícios do uso

Principais vantagens:

• reduz duplicação de código
• mantém documentação consistente
• facilita manutenção
• melhora IntelliSense
• melhora documentação gerada automaticamente

---

Boas práticas

• usar <inheritdoc/> em implementações de interface
• usar em métodos override
• evitar repetir <summary> quando a documentação já existe
• preferir cref quando a origem não é automaticamente detectada

Exemplo recomendado:

/// <inheritdoc cref="ICacheService.GetAsync"/>
public async Task<string> GetAsync(string key)
{
    return await _cache.GetStringAsync(key);
}

---

Limitações

Algumas observações importantes:

• o compilador C# não processa diretamente <inheritdoc>
• a interpretação depende de ferramentas externas
• alguns geradores de documentação antigos podem não suportar totalmente a tag

---