Comentários de documentação XML com interfaces e classe de implementação (es) [fechado]

Question

Estou documentando uma montagem usando Comentários de documentação XML , a partir do qual um chm arquivo será criado usando Sandcastle .

Meu montagem contém várias interfaces, cada uma das quais é implementado por uma classe (no meu cenário estes são serviços WCF).

Eu adicionei a documentação para as interfaces, existe alguma maneira para mim para documentar automaticamente os métodos relevantes sobre as classes de implementação?

Answer 1

Parece não haver qualquer apoio a tal autodocumentation no Sandcastle. A Sandcastle Ajuda Builder Arquivo que implementa uma tag inheritdoc personalizado.

A partir do site SHFB:

O suporte é incluído para o tag que lhe permite documentação herdar a partir da base tipos / membros. Isso é implementado via uma ferramenta autônoma para que ele também pode ser usado por outras ferramentas de terceiros e scripts de construção. Esta ferramenta fornece Possui além daqueles encontrados no componente de construção fornecido com Sandcastle.

Segunda actualização: de acordo com a este item de trabalho , o "apoio" Sandcastle para inheritdoc é através da ferramenta SHFB. Bottom line eu suponho é, SHFB resolve o seu problema.

Answer 2

Eu tenho uma resposta melhor:. fixml

comentários Clonagem com GhostDoc \ AtomineerUtils é 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.

Como foi mencionado, não há tag <inheritdoc> em Sandcastle , 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.

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 .

Answer 3

Uma ferramenta como GhostDoc pode gerar a documentação sobre as classes de execução, quando você usá-lo de atalho de teclado. Isso não é inteiramente automática, mas pode ajudar a prevenir demais colar cópia.

Talvez pudesse ser Automized com um script.

Answer 4

AtomineerUtils irá gerar automaticamente comentários para você, e ele pega documentação de sobrecargas e classe base substituído existente, poupando-lhe um monte de problemas na duplicação da informação onde ela é necessária.

http://www.atomineer.com/AtomineerUtils.html