Documentar bem um código é essencial para o desenvolvimento e manutenção de projetos, principalmente quando esses projetos têm uma equipe de desenvolvimento por trás.

Para projetos em PHP existe uma poderosa ferramenta, o PHPDoc, que é baseado no JAVADoc (ferramenta de documentação da Sun). O objetivo desta ferramenta é padronizar a documentação dos códigos criados em PHP.

O PHPDoc é um projeto Open Source e é distribuído sobre PHP Licence, o que significa que você pode utilizá-lo comercialmente em seus projetos.

Como o PHPDoc funciona?

Basicamente o PHPDoc lê todo o código fonte do projeto procurando por tags especiais (segue uma lista logo abaixo). Com base nessas tags a ferramenta cria a documentação do projeto em diversos formatos como: chm (Windows help), html, pdf, xml.
As tags sempre devem iniciar com @(arroba) dentro dos comentários. Estes comentários, para serem legíveis para o PHPDoc, seguem o seguinte modelo:

Segue a lista com a maioria das tags aceitas pelo PHPDoc:

  •@access - controle de acesso para um elemento. Se for definido como private o elemento não constará na documentação
  •@author - utilizado para indicar o autor de qualquer elemento que possa ser documentado (variáveis globais, funções, classes, métodos, etc.). Nesta tag pode-se adicionar o e-mail entre os sinais de < e >
  •@category - especifica a categoria para organizar os pacotes dos elementos documentados
  •@copyright - informações de copyright do elemento.
  •@deprecated - indica que o elemento está depreciado, sendo assim não deve ser utilizado por pode ser removido posteriormente
  •@example - inclui um arquivo externo de exemplo com sintaxe destacada
  •@final - indica que um método de uma classe nunca deve ser sobrescrito em uma classe filha
  •@filesource - cria a referência cruzada para o arquivo que contem o código fonte
  •@global - documenta uma variável global. Também é utilizado para métodos/funções
  •@ignore - previne o elemento de ser documentado, normalmente utilizado para elementos duplicados
  •@internal - define a documentação como privada, ou seja interna ao projeto
  •@licence - exibe o link para a url que referencia a licença de uso
  •@link - exibe um link na documentação
  •@package - define um pacote para agrupar as classes ou funções
  •@param - documenta um parâmetro da função
  •@return - documenta o retorno de uma função
  •@see - exibe um link para a documentação de um elemento
  •@since - indica desde qual versão o elemento foi adicionado ao projeto
  •@static - documenta uma variável ou método estático
  •@todo - indica as mudanças que serão realizadas no futuro
  •@version - indica a versão do elemento
  •inline {@internal}
  •inline {@inheritdoc}
  •inline {@link}

Bom agora que já conhecemos a maioria das tags do PHPDoc fica extremamente fácil aplicar esse padrão de documentação visando o bom entendimento e relacionamento entre as partes envolvidas na codificação do projeto.

O que vou mostrar agora é um exemplo de código que será documentados pelo PHPDoc.

A instalação do PHPDoc é muito tranqüila, segue o link com o tutorial de instalação: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/ric_INSTALL.html

Bom é isso pessoal, documentar é uma coisa simples mas de suma importância para o desenvolvimento de nossos projetos. Espero que tenham gostado do artigo e que passem a utilizar esse método de documentação em seus projetos.

Referência: PHPDocumentator (http://manual.phpdoc.org/)