PHPDOC – Documentando bem seu código

Neste artigo o autor aborda um pouco sobre documentação de códigos php usando a ferramenta PHPDoc ou PHPDocumentor.

por Leo Genilhu

Olá pessoal, depois de um bom tempo sem escrever aqui nesta coluna volto a todo vapor com uma série de artigos sobre documentação.

Hoje vamos falar um pouco sobre documentação de códigos php usando a ferramenta PHPDoc ou PHPDocumentor. O PHPDoc foi baseado no JAVADoc da Sun e tem como objetivo padronizar a documentação de códigos PHP. Ele lê o código e analisa gramaticalmente procurando por tags especiais. A partir delas extrai toda documentação usando diferentes formatos (pdf, xml, html, chm Windows help e outros). Todas as tags especiais são escritas dentro do comentários do php /*comentários */ e necessariamente começam com o @ (arroba).

Descrição de algumas tags especiais:

• @access Específica o tipo de acesso(public, protected e private).
• @author Específica o autor do código/classe/função.
• @copyright Específica os direitos autorais.
• @deprecated Específica elementos que não devem ser usados.
• @exemple Definir arquivo de exemplo, $path/to/example.php
• @ignore Igonarar código
• @internal Documenta função interna do código
• @link link do código http://www.exemplo.com
• @see
• @since
• @tutorial
• @name Específica o apelido(alias).
• @package Específica o nome do pacote pai, isto ajuda na organização das classes.
• @param Específica os paramêtros muito usado em funções.
• @return Específica o tipo de retorno muito usado em funções.
• @subpackage Específica o nome do pacote filho.
• @version Específica a versão da classe/função.
• Inline { @internal

Exemplo parte de código documentado com PHPDoc.

<?php
/** 
 * Comentário de cabeçalho de arquivos
* Esta classe de upload de fotos
*
* @author leo genilhu <leo@genilhu.com>
* @version 0.1 
* @copyright  GPL © 2006, genilhu ltda. 
* @access public  
* @package Infra_Estrutura 
* @subpackage UploadGenilhu
* @example Classe uploadGenilhu. 
*/ 


class uploadGenilhu {
  /** 
    * Comentário de variáveis
    * Variável recebe o diretório para gravar as fotos. 
    * @access private 
    * @name $diretorio 
    */ 
    var $diretorio = "" ;

  /** 
    * Função para  gravar imagem em diretório
    * @access public 
    * @param String $imagem_nome
    * @param String $diretorio
    * @return void 
    */ 
   function upload_up($imagem_nome, $diretorio)
    {
        $tmp = move_uploaded_file($this->arquivo["tmp_name"], $diretorio);
        return($tmp);
    } 
?>

Como instalar o PHPDoc?

Há dois metódos oficiais para a instalação do PHPDocumentor, você pode baixar o PHPDoc direto do site sourceforge.net. Para instalar pasta descompactar o arquivo .zip e criar um diretorio de trabalho phpdoc.

Outra forma é usar a versão distribuída no pacote PEAR. Para instalar basta executar o comando abaixo
$ pear install PhpDocumentor

Como gerar relatórios de phpdoc usando o ZEND?

O Editor PHP ZEND vem com uma interface integrada para gerar seus relatórios de documentação.
Para isso basta seguir as instruções através do menu tools --> PHPDocumentor.
Outra forma de gerar a documentação e via shell do linux.
$phpdoc -o HTML:frames:earthli -f arquivo.php -t docs

Mais curiosidades consulte a documentação no site oficial: phpdoc.org.

Um abraço a todos e até aproxima.

Leo Genilhu

Fontes:

www.phpdoc.org

http://pear.php.net/package/PHPDoc

http://sourceforge.net/projects/phpdoc/