Maneiras de sincronizar a interface e os comentários de implementação em C # [fechado]

Existem maneiras automáticas de sincronizar comentários entre uma interface e sua implementação? No momento, estou documentando os dois e não gostaria de mantê-los sincronizados manualmente.

ATUALIZAR:

Considere este código:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Quando eu crio uma classe assim:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Aqui os comentários não são mostrados:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

A <inheritDoc/>tag irá gerar perfeitamente a documentação no Sand Castle, mas não funciona nas dicas de ferramentas do Intellisense.

Por favor, compartilhe suas idéias.

Obrigado.

Você pode fazer isso facilmente usando a inheritdoctag Microsoft Sandcastle (ou NDoc) . Não é oficialmente suportado pela especificação, mas as tags personalizadas são perfeitamente aceitáveis ​​e, de fato, a Microsoft optou por copiar isso (e uma ou duas outras tags) do NDoc quando criou o Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Aqui está a página de ajuda da GUI do Construtor de Arquivos de Ajuda do Sandcastle, que descreve seu uso por completo.

(Claro, isso não é especificamente "sincronização", como sua pergunta menciona, mas parece ser exatamente o que você está procurando, no entanto.)

Como observação, essa ideia parece perfeitamente justa para mim, embora tenha observado que algumas pessoas acham que você sempre deve especificar novamente os comentários em classes derivadas e implementadas. (Na verdade, eu mesmo fiz isso ao documentar uma de minhas bibliotecas e não vejo nenhum problema.) Quase sempre não há razão para os comentários serem diferentes, então por que não apenas herdar e fazer da maneira mais fácil?

Edit: Em relação à sua atualização, o Sandcastle também pode cuidar disso para você. O Sandcastle pode produzir uma versão modificada do arquivo XML real que usa para entrada, o que significa que você pode distribuir essa versão modificada junto com sua biblioteca DLL em vez daquela construída diretamente pelo Visual Studio, o que significa que você tem os comentários no intellisense, bem como o arquivo de documentação (CHM, qualquer que seja).

Se você ainda não estiver usando, eu recomendo fortemente um complemento gratuito do Visual Studio chamado GhostDoc . Facilita o processo de documentação. Dê uma olhada no meu comentário sobre uma questão um tanto relacionada.

Embora o GhostDoc não faça a sincronização automaticamente, ele pode ajudá-lo no seguinte cenário:

Você tem um método de interface documentado. Implemente essa interface em uma classe, pressione a tecla de atalho GhostDoc Ctrl-Shift-D, e o comentário XML da interface será adicionado ao método implementado.

Vá para Opções -> Configurações do teclado e atribua uma tecla a GhostDoc.AddIn.RebuildDocumentation(eu usei Ctrl-Shift-Alt-D).

Agora, se você alterar o comentário XML na interface , basta pressionar esta tecla de atalho no método implementado, e a documentação será atualizada. Infelizmente, isso não funciona vice-versa.

Normalmente escrevo comentários como este:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Os métodos são usados ​​apenas pela interface, portanto, esse comentário nem mesmo é mostrado nas dicas de ferramentas durante a codificação.

Editar:

Se você quiser ver os documentos ao chamar a classe diretamente e não usando a interface, precisará escrevê-los duas vezes ou usar uma ferramenta como o GhostDoc.

Experimente o GhostDoc ! Funciona para mim :-)

Edit: Agora que fui informado do apoio do Sandcastle para <inheritdoc/>, endosso o post de Noldorin. É uma solução muito melhor. Ainda assim, recomendo o GhostDoc de maneira geral.

Tenho uma resposta melhor: FiXml . , Eu sou um de seus autores

A clonagem de certamente funciona, mas tem desvantagens significativas, por exemplo:

• Quando o comentário original é alterado (o que freqüentemente acontece durante o desenvolvimento), seu clone não é.
• Você está produzindo uma grande quantidade de duplicatas. Se você estiver usando qualquer ferramenta de análise de código-fonte (por exemplo, Duplicate Finder no Team City), ele encontrará principalmente seus comentários.

Como foi mencionado, existe <inheritdoc>tag no Sandcastle , mas tem poucas desvantagens em comparação com FiXml:

• O Sandcastle produz arquivos de ajuda HTML compilados - normalmente não modifica .xmlarquivos contendo comentários XML extraídos (por fim, isso não pode ser feito "em tempo real" durante a compilação).
• A implementação do Sandcastle é menos poderosa. Por exemplo, o é não <see ... copy="true" />.

Veja a <inheritdoc>descrição do Sandcastle para mais detalhes.

Breve descrição do FiXml: é um pós-processador de documentação XML produzido por C # \ Visual Basic .Net. Ele é implementado como uma tarefa MSBuild, portanto, é muito fácil integrá-lo a qualquer projeto. Ele aborda alguns casos irritantes relacionados à escrita de documentação XML nestas linguagens:

• Sem suporte para herdar a documentação da classe base ou interface. Ou seja, uma documentação para qualquer membro sobrescrito deve ser escrita do zero, embora normalmente seja bastante desejável herdar pelo menos parte dela.
• Não há suporte para a inserção de modelos de documentação comumente usados , como “Este tipo é singleton - use sua <see cref="Instance" />propriedade para obter a única instância dele.”, Ou mesmo “Inicializa uma nova instância de <CurrentType>classe”.

Para resolver os problemas mencionados, as seguintes tags XML adicionais são fornecidas:

• <inheritdoc />, <inherited /> Tag
• <see cref="..." copy="..." />atributo na <see/>tag.

Aqui está sua página da web e página de download .

/// <inheritDoc/>

Leia aqui

Usa isto

Eu construí uma biblioteca para pós-processar os arquivos de documentação XML para adicionar suporte para a tag <inheritdoc />.

Embora não ajude com o Intellisense no código-fonte, permite que os arquivos de documentação XML modificados sejam incluídos em um pacote NuGet e, portanto, funciona com o Intellisense em pacotes NuGet referenciados.

Mais informações em www.inheritdoc.io (versão gratuita disponível).

Não faça isso. Pense desta forma - se ambos os comentários devem ser iguais o tempo todo, então um deles não é necessário. Deve haver um motivo para o comentário (além de algum tipo de obrigação estranha de bloquear comentários em todas as funções e variáveis), então você precisa descobrir qual é esse motivo único e documentá-lo.

Com o ReSharper você pode copiá-lo, mas não acho que ele esteja sincronizado o tempo todo.