docs XML .NET - documentação herdando

Question

NDoc tem um elemento XML inheritdoc que lhe permite documentação herdar de um membro da classe pai (ou uma interface implementada). No entanto, Visual Studio (ou seja, o compilador C #) não entende essa tag e reclama da documentação não estar presente ou completa. O mesmo acontece com StyleCop e algumas outras ferramentas. Existe uma abordagem alternativa? Como é que você vai manter a documentação completa, ainda sem duplicar as descrições XML?

Answer 1

Uma alternativa é usar GhostDoc - um add-in para o Visual Studio que gera automaticamente comentários para você. Isto duplica a descrição XML é claro, que é parte do que você está tentando evitar -., Mas pelo menos ele faz isso automaticamente para você

O que acontece se você simplesmente deixar de fora os docs inteiramente para métodos que estão sendo herdadas, ou imperativas métodos de interface? Eu suspeito que isso depende de como você tem NDoc configurado, mas certamente no MSDN documentação parece apenas naturalmente herdar o docs - e uma verificação rápida sugere que VS não vai whinge quando você não Prodive docs para um método herdado. Vale a pena tentar, certamente.

Answer 2

Eu tenho uma resposta melhor:. fixml

comentários Clonagem com GhostDoc é certamente abordagem de trabalho, 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 quantidade enorme de duplicatas. Se você estiver usando qualquer ferramentas de análise de código fonte (por exemplo Duplicate Finder no Team City), que vai encontrar principalmente seus comentários.

Breve descrição do fixml: é um pós-processador de documentos XML produzido pela C # \ Visual Basic .Net. Ele é implementado como tarefa MSBuild, por isso é bastante fácil de integrá-lo a qualquer projeto. Ele aborda alguns casos irritantes relacionados a escrever documentação XML em línguas seguintes:

• Não há suporte para herdar a documentação da classe base ou interface. Ou seja a documentação para qualquer membro substituído deve ser escrito a partir do zero, embora normalmente é bastante desejável para herdar pelo menos a parte dela.
• Não há suporte para a inserção de documentação comumente usados ??modelos , como “Este tipo é Singleton -. Usar sua propriedade <see cref="Instance" /> para obter o único exemplo disso”, ou mesmo “inicializa uma nova instância classe <CurrentType> “.

Para resolver questões mencionadas, as seguintes tags XML adicionais são fornecidos:

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

Aqui está sua página web e página de download (links quebrados).

Finalmente, há tag <inheritdoc> em Sandcastle - é definitivamente melhor para usá-lo do que para copiar comentários XML, mas tem algumas desvantagens em comparação com fixml:

• Sandcastle produz arquivos de ajuda HTML compilados - não modificar arquivos .xml contendo comentários XML extraídos. Mas esses arquivos são usados ??por muitas ferramentas, Incluindo .NET Reflector e classe navegador \ IntelliSense no Visual Studio .NET. Então, se você usar apenas Sandcastle, você não vai ver a documentação herdou lá.
• A implementação do Sandcastle é menos potente. Por exemplo. o não é <see ... copy="true" />.

<inheritdoc> descrição do Sandcastle de mais detalhes.

Answer 3

Eu construí uma ferramenta de linha de comando para pós-processar os arquivos de documentação XML para adicionar suporte para o tag.

Não ajuda com Intellisense em código fonte, mas ele permite que os arquivos de documentação XML modificados para ser incluído em um pacote NuGet e, portanto, trabalha com Intellisense em pacotes NuGet referenciados.

www.inheritdoc.io para mais detalhes (versão gratuita disponível).