Documentação de Software

Escrito porJackson F. de A. Mafra

dezembro 13, 2006

Você produz software? Certamente para muitos esta é uma pergunta simples de ser respondida. Para tantos outros pode parecer estranha a utilização do termo “produz” relacionado ao desenvolvimento de software.

Entretanto, o processo de desenvolvimento de um software envolve uma série de etapas que visam a geração de um produto principal, o software. No decorrer destas etapas, vários subprodutos são concebidos, e um deles é a documentação.

A documentação é um poderoso artefato que permite com que as pessoas envolvidas em um projeto entendam seu funcionamento, e as particularidades de determinado código fonte. Porém, nem sempre a documentação é elaborada. Isto ocorre, muitas vezes, devido à falta de tempo para a conclusão do projeto, ou pelo simples fato de o programador ter que deixar de lado o que ele gosta de fazer, escrever o código fonte, para escrever sobre o código fonte.

Existem ferramentas que facilitam a vida do programador na hora de gerar a documentação. Irei abordar neste artigo a utilização do PHPDocumentor, uma excelente ferramenta para a linguagem PHP que gera automaticamente a documentação, baseada em tags próprias contidas nos códigos fonte.

Como documentar seu fonte

Para gerar a documentação, o PHPDocumentor realiza uma varredura nos programas, buscando por tags específicas, para então tratá-las de acordo com suas propriedades. As tags iniciam pelo caracter @ e devem estar contidas dentro de blocos de comentário especiais.

Na imagem a seguir, pode-se observar um exemplo simples da utilização dos comentários para documentação.

Nas linhas 3 e 9 temos, respectivamente, o identificador de início e fim de um bloco de comentários que será analisado pelo PHPDocumentor.

Logo em seguida, na linha 4, é feita uma descrição sobre a principal funcionalidade da classe.

As tags utilizadas no exemplo foram @author e @version que servem para identificar o autor e a versão atual do código fonte. Note que o que separa a tag da sua descrição é apenas um espaço, isto é, todo o texto encontrado após este espaço é atribuído à tag.

O PHPDocumentor fornece várias outras tags para documentação. Apresento neste código fonte um exemplo de utilização das principais tags, e nas linhas seguintes uma breve explicação sobre suas funcionalidades:

@access
Permite definir uma restrição para inclusão de um elemento na documentação gerada, podendo receber os valores private, protected ou public. Quando o valor private for atribuído à tag, o elemento subseqüente não estará contido na documentação, a menos que a inclusão deste seja definida no momento da geração do documento.

@author
É utilizada para definir o autor do código fonte, podendo ser seguido de um e-mail, conforme exemplificado na primeira imagem. Quando informado um e-mail, será apresentado um link para o mesmo na documentação gerada.

@copyright
Informações sobre os direitos autorais.

@example
Permite que sejam inseridos exemplos, podendo estar contidos num arquivo, cujo caminho deve ser especificado após a tag @example, ou descritos diretamente entre as tags <code> … </code>

@ignore
Faz com que o gerador de documentação ignore um elemento. Pode ser utilizada para evitar que sejam descritos elementos em duplicidade.

@internal
Permite que sejam definidos blocos para serem omitidos no momento da geração da documentação. Um exemplo prático da utilização deste recurso é a geração de documentos diferentes para públicos-alvo diferentes, ou seja, podem ser omitidas da versão para usuários informações relevantes apenas aos desenvolvedores. Possui funcionalidade semelhante a tag @access.

@license
Pode ser utilizada para informar a URL onde se encontram informações sobre a licença do software.

@package e @subpackage
Facilitam a organização do documento gerado, pois com elas é possível criar pacotes e subpacotes de elementos. No nosso exemplo, foi criado o pacote “Segurança” e o subpacote “Usuários”, contendo a classe “Usuario”.

@param
Utilizada para documentar um parâmetro de um método ou função, permitindo especificar o tipo de dado, o nome da variável e sua descrição.

@return
Permite informar qual o tipo de dado e a descrição do retorno de uma função ou método.

@since
É utilizada para especificar a partir de qual versão um elemento foi adicionado ao programa.

@var
Possibilita a documentação de variáveis. Podem ser informados o tipo de dado e uma descrição sobre a variável. Utiliza-se o tipo de dado “mixed” quando o tipo da variável não está definido.

Gerando a documentação

Para baixar o PHPDocumentor, acesse www.phpdoc.org. A instalação é bastante simples, resumindo-se em extrair os arquivos do pacote baixado para um diretório acessível ao seu servidor de aplicações web. Sugiro que extraiam o conteúdo do pacote para o diretório phpdocumentor. Para maiores informações sobre a instalação do PHPDocumentor, consulte o manual existente no site do fabricante.

O pacote de instalação da versão 1.3.0 pode apresentar algumas inconsistências quanto à localização de alguns arquivos do sistema, o que fará com que a interface web não seja exibida corretamente. Eu preparei um patch para corrigir estes problemas. Clique aqui para fazer o download das correções.

Com o PHPDocumentor instalado, iremos gerar nossa primeira documentação utilizando o arquivo exemplo apresentado anteriormente.

Para isto, acesse a interface web do PHPDocumentor. No meu caso, o link é http://localhost/phpdocumentor/index.html, pois descompactei o pacote de instalação na subpasta phpdocumentor do diretório onde o meu servidor de aplicações acessa os documentos web.

Após acessar o PHPDocumentor, clique na aba “Files” para informar quais arquivos serão processados para geração da documentação. Preencha conforme a imagem abaixo, alterando o caminho do arquivo de acordo com a localização do mesmo no seu computador.

Para informar um diretório e obter a documentação de todos os arquivos contidos nele, utilize o campo “Directory to parse”. Para ignorar arquivos durante a geração da documentação deve-se utilizar o campo “Files to ignore”.

Vamos, agora, na aba “Output”, configurar o local onde serão armazenados os arquivos de documentação gerados e o formato dos mesmos. No campo “Target” informe o diretório que receberá os arquivos gerados, e no listbox abaixo de “Output format” selecione o formato do documento a ser gerado e clique em “Add the converter in the help box”.

O próximo passo é a aba “Options”, onde definiremos o título do documento através do campo “Generated Documentation Title”.

Como utilizamos em nosso código fonte a tag @access para que seja possível criar documentos com conteúdo diferenciado para usuários e para desenvolvedores, iremos primeiramente deixar a opção “Parse @access private and @internal/{@internal}}” desmarcada, fazendo com que o gerador ignore todos os elementos identificados com a tag @access private e @internal. Para gerar a documentação, clique em “create”.

Se tudo estiver correto, a mensagem “Operation Completed!” será exibida no quadro inferior da tela. Verifique a documentação no diretório informado para geração dos arquivos.

É isso aí pessoal, este foi meu primeiro artigo no iMasters, espero que tenham gostado. Caso queiram entrar em contato comigo ou me enviar sugestões de tema para os próximos artigos, basta me encaminhar um e-mail.