Atenção: esse artigo tem um vídeo complementar. Clique e assista!
Este artigo tem por objetivo demonstrar como a documentação de elementos para classes, propriedades e métodos pode ser feita dentro da plataforma .NET, através de comentários em XML. Desta forma, você tem a possibilidade de gerar documentos de ajuda em um formato similar àquele empregado pelo MSDN(Microsoft Developer Network).
Em que situação o tema é útil
Além de possibilitar uma documentação padronizada para os diversos tipos de construções de código disponíveis na plataforma .NET, comentários XML são bastante úteis por fornecer a base para que as informações contidas sejam exibidas como dicas através do ambiente de desenvolvimento (IDE) do Visual Studio. Este tipo de recurso também serve para a geração de arquivos de ajuda, detalhando elementos como classes, interfaces, métodos, eventos, delegates, etc.
Documentação em .NET - Utilizando comentários em XML para documentar o código-fonte
Quando se leva em conta atividades que envolvam a escrita de código-fonte, é bastante comum que desenvolvedores utilizem as dicas fornecidas pela IDE do Visual Studio, orientando-se a respeito de como elaborar uma determinada instrução, ou obter esclarecimentos sobre de que maneira um determinado recurso (ex: métodos) pode ser empregado. Isto pode acontecer não apenas com a utilização de construções próprias da plataforma .NET, como também quando da utilização de frameworks contendo componentes e outros recursos disponibilizados por terceiros. É provável ainda que consultas sejam feitas à documentação existente no site do MSDN ou em arquivos disponibilizados pelos fornecedores dos prováveis controles específicos. Os diversos formatos de comentários em XML disponibilizados pelo .NET Framework(e que será abordado neste artigo), permitem não apenas a geração de diversos tipos de documentação, assim como possibilitam detalhar de uma maneira bem estruturada o funcionamento das mais variadas estruturas de código.
O ambiente de desenvolvimento (IDE) do Visual Studio conta com uma ampla gama de recursos, tendo sido projetados para facilitar a vida dos profissionais de programação em suas atividades rotineiras. Exemplo disso é a de dicas referentes a uma estrutura durante a digitação de instruções: isto normalmente ocorre em conjunto com a utilização de um mecanismo conhecido como Intellisense, com informações detalhadas sobre uma classe ou método, por exemplo, sendo apresentadas ao usuário de forma a auxiliá-lo a compreender melhor o funcionamento de um elemento que pretende vir a empregar.
Informações deste tipo e que descrevem aspectos de uma estrutura podem também constar num arquivo de ajuda, ou ainda, em um site concebido justamente para este fim. A documentação organizada neste formato permite que os diferentes dados relativos a um conjunto de recursos fiquem centralizados em um único local, facilitando a pesquisa por algum elemento requerido dentro de um determinado contexto.
Tanto fornecedores de soluções proprietárias, quanto equipes internas de desenvolvimento de uma empresa poderão se deparar, no transcorrer de um projeto específico, com a necessidade de disponibilizarem explicações e outros detalhamentos a respeito de recursos que estão sendo implementados.
No caso de fornecedores de software, arquivos de ajuda e dicas que serão exibidas por meio de uma IDE, permitem basicamente, que desenvolvedores de clientes que adquiriram um produto possam conhecer melhor a estrutura e características deste.
Já aplicações criadas internamente em organizações podem fazer uso de uma série de funcionalidades genéricas, constando em bibliotecas projetadas especialmente para a reutilização ao longo de uma ou mais soluções. Tais funções podem então vir a ser documentadas, contribuindo não apenas para um melhor entendimento de como as mesmas se encontram estruturadas, como também possibilitando que as informações empregadas em tal processo possam ser usadas em IDEs ou na geração de arquivos de ajuda.
IDE - Integrated Development Environment é um programa de computador que reúne características e ferramentas de apoio ao desenvolvimento de software com o objetivo de agilizar este processo. Geralmente os IDEs facilitam a técnica de RAD (Rapid Application Development), que visa gerar maior produtividade aos desenvolvedores.
O intuito deste artigo é apresentar como comentários em XML podem ser aplicados para a documentação de código-fonte. A partir disso, uma aplicação de exemplo será criada, fechando-se a discussão sobre como documentar estruturas de código com a geração de um arquivo de ajuda a partir de uma ferramenta da Microsoft, conhecida como Sandcastle.
O Intellisense é um conjunto de recursos existentes dentro do Visual Studio e que tem por função, basicamente, fornecer meios que facilitem o trabalho de codificação de aplicações na plataforma .NET e que gerem como resultado uma maior produtividade em atividades de desenvolvimento de software. O Visual Studio disponibiliza uma série de funcionalidades integradas ao ambiente de desenvolvimento.
Existem mecanismos no Intellisense para a inserção de trechos de código em um formato padronizado (inclusão de um comentário de documentação) ou, ainda, que permitem completar a digitação de uma instrução a partir da seleção de prováveis opções em uma lista (invocação de um método, por exemplo). Outras opções oferecidas pelo Intellisense são a apresentação de informações de ajuda sobre estruturas de classes e métodos e o suporte para completar a digitação de instruções em Javascript ou SQL.
