Gerador de documentação do RAD Studio

Uma das coisas mais interessantes nas novas versões do RAD Studio e que, pelo que vejo, ainda não é explorado adequadamente pelos desenvolvedores, é o adorável gerador de documentação. Muitos já o conhecem, ou mesmo já ouviram falar, mas poucos exploram efetivamente seus recursos. A documentação do software é um dos tesouros mais sagrados de uma empresa, visto que provê comunicação entre os diversos setores da organização. Facilita o entendimento entre Analistas, Arquitetos, Programadores, Gerentes, Estagiários e qualquer outro interessado. Garante a agilidade dos processos internos, pois facilita o entendimento e transmite segurança aos profissionais, que na maioria das vezes, estão em ambientes que exigem uma atuação sobre-humana. É, além de tudo e principalmente, elemento de grande importância na diminuição dos riscos nas análises das empresas, pois garante que o conhecimento será perpetuado em caso de problemas.

O que é fantástico é que o RAD Studio nos fornece a documentação praticamente pronta. Só com as informações geradas, sem que nada seja feito, já é possível possuir uma rica fonte de informação sobre o software.

Abaixo encontra-se um exemplo de documentação gerada pelo RAD Studio:

Caso não esteja familiarizado com o gerador de documentação e queira dar uma olhadinha, basta habilitar o suporte a modelagem em seu projeto (Project->Modeling Support) . Com o suporte a modelagem habilitado, você será capaz de visualizar a modelagem (View-> Model View) e gerar a documentação a partir dela, clicando com o botão direito do mouse e depois em “Generate Documentation”. Os passos a seguir são auto-explicativos.

Mas é possível ir além, e incluir suas próprias informações na documentação, deixando-a ainda mais poderosa, e adequando-a à sua organização, de uma maneira incrivelmente fácil. Todos conhecem os comentários padrão do Delphi:

Esses comentários, embora úteis na geração de informações aos desenvolvedores, não são exportados juntos na documentação gerada, não integrando a documentação final do sistema. Mas há a possibilidade de inserirmos um comentário de barra tripla, conforme abaixo:

Comentários de barras triplas tem a característica de serem gerados juntos com a documentação. Isso nos dá a possibilidade de aprimorá-la com informações e características que sejam relevantes à nossa organização, tornando-a ainda mais rica e interessante. Outro elemento que é importante ser mencionado é que a documentação categoriza-se pela utilização de TAGS, que no final serão vistas como títulos. Vejamos uma classe pessoa sendo documentada. Supomos que eu queira criar um tópico com a descrição completa da classe, a nível organizacional, coisa que o gerador de doumentação não realizará sozinho. Eu teria algo parecido a:

Repare que criamos a documentação logo a cima da classe TPessoa. Isso irá caracterizar que a documentação é referente à classe TPessoa. Outro ponto a se notar é a utilização da TAG , que limita o escopo da documentação. Antes de visualizarmos o resultado disso na documentação final, vamos documentar os métodos Andar e Falar, mostrando como é possível criar uma documentação detalhada da classe:

Perceba que os métodos estão documentados da mesma forma, com os comentários de barras triplas logo a cima de suas declarações. Utilizei a mesma TAG de , mas poderia ser utilizada qualquer outra TAG. O resultado disso é o que temos a seguir:

Repare como nossa documentação passou a fazer parte da documentação gerada pelo RAD Studio. Ao analisarmos os métodos individualmente, veríamos que o mesmo ocorreu com eles.

Você pode estar pensando que tudo isso é bem legal, mas que como agora todo essa documentação está lá no código, a visualização do código em sí tornou-se algo muito difícil, visto que agora ela está “sujando” todo o texto do editor. De fato é verdade, e antes um software mal documentado do que um ilegível. Mas graças aos nossos amigos da Embarcadero, podemos utilizar o recurso das “Regions” que “esconderá” toda área indesejada para nós.

Para a criação de uma region, basta:

Repare que o editor adicionou o sinal de + e -, onde você agora pode expandir ou diminuir o conteúdo dentro de uma region. Aplicando isso à nossa documentação, teríamos o seguinte:

Dessa forma você consegue documentar facilmente seu sistema e ainda torná-la elegante dentro do código.