Como documentar seu código .NET com comentários XML

Em qualquer ambiente profissional, documentar adequadamente seu código com comentários é necessário para uma legibilidade de longo prazo. Para código . NET, a Microsoft fornece um sistema para comentários baseados em XML que fornecem suporte IDE aprimorado.

O que são comentários XML?

Essencialmente, os comentários XML são um tipo especial de comentário denotado por uma barra tripla (///) e marcas XML para dar ao comentário alguma estrutura. Por exemplo, um simples comentário resumido seria semelhante ao seguinte:

O objetivo disso é que, quando você for usar esse método em outro lugar em seu código, o Visual Studio poderá examinar o XML e adicionar algumas informações diretamente no pop-up do Intellisense. Este sistema funciona para todos os tipos de tipos e pode até ser usado para documentar valores de retorno e parâmetros individuais. E, ao distribuir o assembly, você pode distribuir o arquivo XML com ele para habilitar esses mesmos recursos para qualquer pessoa que use sua biblioteca de classes. Isso também permite o uso fácil de geradores de documentação estática, como DocFX e Sandcastle.

Surpreendentemente, esse recurso é basicamente apenas uma coisa . NET. Nada impede que você use a prática com outros idiomas, mas é algo que a Microsoft suporta bem para seus idiomas e editores, e outros idiomas geralmente não têm o suporte adequado para isso. Adoraríamos ver o suporte expandido para outros idiomas e editores, pois é universalmente útil.

É muito simples de usar. Simplesmente pressione a tecla de barra três vezes (///) acima de um método, classe ou outro tipo, e o Visual Studio irá inserir um modelo para você digitar. Isso evita o incômodo de digitar manualmente, o que significa que há &’ realmente não há razão para não usar esses comentários tradicionais de barra dupla.

Se o seu método tiver um tipo de retorno ou parâmetros, o Visual Studio gerará campos para eles também. Você verá seus comentários quando for usar o método:

O padrão suporta muitos tipos de tags:

• < resumo > é exibido no Intellisense sempre que você usa o método.
• < observações > é como um resumo, mas não aparece no Intellisense (útil para escrever documentação estendida).
• < retorna > documenta o tipo de retorno.
• < exception > permite que os desenvolvedores saibam quais exceções o método pode lançar.
• < value > é como retorna, mas para propriedades de classe.
• < exemplo > mostra um exemplo de código para a documentação (use-o com < code >).
• < consulte > e < seealso > gerar links clicáveis ​​para outros métodos, geralmente usados ​​para documentar sobrecargas.
• < list > permite o uso de listas para ordenar os elementos.

Você pode ler a documentação da Microsoft sobre o padrão de comentário XML para obter mais informações.

Via: How to Geek