Herança de comentários para C # (na verdade, qualquer linguagem)

Suponha que eu tenha esta interface

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

E esta aula

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

Existe uma maneira ou existe uma ferramenta que pode me deixar colocar automaticamente os comentários de cada membro em uma classe base ou interface?

Porque eu odeio reescrever os mesmos comentários para cada subclasse derivada!

GhostDoc faz exatamente isso. Para métodos que não são herdados, ele tenta criar uma descrição a partir do nome.

FlingThing() torna-se "Flings the Thing"

Você sempre pode usar <inheritdoc />tag.

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

Use /// <inheritdoc/>se quiser herança. Evite GhostDoc ou algo parecido.

Concordo que é irritante que os comentários não sejam herdados. Seria um suplemento bastante simples de criar se alguém tivesse tempo (gostaria de ter).

Dito isso, em nossa base de código, colocamos comentários XML apenas nas interfaces e adicionamos comentários de implementação extras à classe. Isso funciona para nós, pois nossas classes são privadas / internas e apenas a interface é pública. Sempre que usamos os objetos por meio das interfaces, temos todos os comentários exibidos na inteligência.

GhostDoc é um bom começo e tornou o processo mais fácil de escrever comentários. É especialmente útil manter os comentários atualizados ao adicionar / remover parâmetros, executar novamente o GhostDoc e ele atualizará a descrição.

Java tem isso e eu uso o tempo todo. Apenas faça:

/**
 * {@inheritDoc}
 */

E a ferramenta Javadoc descobre isso.

C # tem marcador semelhante:

<inheritDoc/>

Você pode ler mais aqui:

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

Eu diria para usar diretamente o

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

E

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

Você deve colocar esses comentários apenas na linha anterior de sua classe / método

Isso obterá as informações de seus comentários, por exemplo, de uma interface que você documentou como:

    /// <summary>
    /// This method is awesome!
    /// </summary>
    /// <param name="awesomeParam">The awesome parameter of the month!.</param>
    /// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
    AwesomeObject CreateAwesome(WhateverObject awesomeParam);

Resharper tem a opção de copiar os comentários da classe base ou interface.

Outra maneira é usar a <see />tag de documentação XML. Este é um esforço extra, mas funciona fora da caixa ...

aqui estão alguns exemplos:

/// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
    /// <summary>
    /// See <see cref="IFoo"/>.
    /// </summary>
    public void Foo() { ... }

    /// <summary>
    /// See <see cref="IFoo.Bar"/>
    /// </summary>
    public void Bar() { ... }

    /// <summary>
    /// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
    /// </summary>
    public void Snafu() { ... }
}

Atualizar:

Agora prefiro usar o /// <inheritdoc/>que agora é compatível com ReSharper.

Acabei criando uma ferramenta para pós-processar os arquivos de documentação XML para adicionar suporte para a substituição da <inheritdoc/>tag nos próprios arquivos de documentação XML. Disponível em www.inheritdoc.io (versão gratuita disponível).

Bem, existe um tipo de solução nativa que encontrei para o .NET Core 2.2

A ideia é usar <include>tag.

Você pode adicionar <GenerateDocumentationFile>true</GenerateDocumentationFile>seu .csprojarquivo.

Você pode ter uma interface:

namespace YourNamespace
{
    /// <summary>
    /// Represents interface for a type.
    /// </summary>
    public interface IType
    {
        /// <summary>
        /// Executes an action in read access mode.
        /// </summary>
        void ExecuteAction();
    }
}

E algo que herda disso:

using System;

namespace YourNamespace
{
    /// <summary>
    /// A type inherited from <see cref="IType"/> interface.
    /// </summary>
    public class InheritedType : IType
    {
        /// <include file='bin\Release\netstandard2.0\YourNamespace.xml' path='doc/members/member[@name="M:YourNamespace.IType.ExecuteAction()"]/*'/>
        public void ExecuteAction() => Console.WriteLine("Action is executed.");
    }
}

Ok, é um pouco assustador, mas adiciona os elementos esperados ao YourNamespace.xml.

Se você construir Debuga configuração, você pode trocar Releasepara Debugno fileatributo da includetag.

Para encontrar uma referência correta member, namebasta abrir o Documentation.xmlarquivo gerado .

Também presumo que essa abordagem requer que um projeto ou solução seja compilado pelo menos duas vezes (a primeira vez para criar um arquivo XML inicial e a segunda vez para copiar elementos dele para si mesmo).

O lado bom é que o Visual Studio valida os elementos copiados, então é muito mais fácil manter a documentação e o código em sincronia com a interface / classe base, etc (por exemplo, nomes de argumentos, nomes de parâmetros de tipo, etc).

No meu projeto, terminei com <inheritdoc/>(para DocFX) e <include/>(para publicação de pacotes NuGet e para validação no Visual Studio):

        /// <inheritdoc />
        /// <include file='bin\Release\netstandard2.0\Platform.Threading.xml' path='doc/members/member[@name="M:Platform.Threading.Synchronization.ISynchronization.ExecuteReadOperation(System.Action)"]/*'/>
        public void ExecuteReadOperation(Action action) => action();