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

98

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.

Valentin Vasilyev
fonte
Este recurso está implementado? visualstudio.uservoice.com/forums/121579-visual-studio/…
hellboy
Como posso fazer o Atomineer Pro permitir a geração da tag de documentação <inheritDoc /> para implementação se a documentação da interface estiver disponível?
hellboy
3
Você está certo <inheritdoc/>está quebrado no Visual Studio. Vote
Coronel Panic

Respostas:

62

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).

Noldorin
fonte
Ei, isso é muito bom! Eu gosto do Sandcastle!
Tor Haugen
Postagem editada para responder a pergunta atualizada.
Noldorin
2
isso pode ser feito em nível de classe? para que eu não precise colocar /// <inheritdoc /> antes de cada método.
Antony Scott
1
Uma coisa que percebi é que <inheritdoc/> não herda a documentação da <param>tag.
stephen,
1
Vote neste recurso de voz do usuário para ter <inheritdoc /> oficialmente adicionado à especificação C # e trabalhar com o VS intellisense visualstudio.uservoice.com/forums/121579-visual-studio/…
deadlydog
14

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). texto alternativo

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.

Igal Tabachnik
fonte
A versão mais recente (5.3.16270) do GhostDoc também pode criar documentos herdados. Eu apenas tentei para minhas implementações de interface. Belo bônus, também adiciona as exceções com a mensagem da exceção lançada :-)
Christoph
6

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.

Stefan Steinegger
fonte
4

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.

Tor Haugen
fonte
6
Pessoalmente, não gosto do GhostDoc. Ele gera documentação onde não há nenhuma. Isso está escondendo o fato de que algo não está documentado. Apenas uma opinião pessoal, não digo que seja algo ruim em geral.
Stefan Steinegger
1
Concordo com o comentário de Stefan em que GhostDoc não é perfeito, no entanto, ele puxa automaticamente comentários "herdados" como este, então é uma boa resposta para a pergunta.
Steve
Stefan, eu discordo - pelo contrário, porque GhostDoc apenas reflete a documentação que você já "colocou" em seus nomes de membro (construindo prosa a partir dos nomes), ele apenas gera documentação onde a documentação já existe (implicitamente). Como tal, não "produz" nada, mas a prosa gerada é um excelente ponto de partida ao qual você pode agregar valor real. A documentação real ainda dá trabalho.
Tor Haugen
2

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 .

Alex Yakunin
fonte
1
/// <inheritDoc/>

Leia aqui

Usa isto

Krzysztof Kozmic
fonte
1

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).

K Johnson
fonte
0

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.

1800 INFORMAÇÕES
fonte
3
Eu não teria usado a interface aqui se não estivesse fingindo nos testes.
Valentin Vasilyev
0

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

Crauscher
fonte