Olá pessoal, depois de um bom tempo sem escrever aqui 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 Especifica o tipo de acesso(public, protected e private).
@author Especifica o autor do código/classe/função.
@copyright Especifica os direitos autorais.
@deprecated Especifica 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 Especifica o apelido(alias).
@package Especifica o nome do pacote pai, isto ajuda na organização das classes.
@param Especifica os paramêtros muito usado em funções.
@return Especifica o tipo de retorno muito usado em funções.
@subpackage Especifica o nome do pacote filho.
@version Especifica 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
* @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 bastas 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.
Gostaria também de acrescentar que a partir de Maio estarei escrevendo em uma coluna especifica no SQLMagazine onde falarei entre outras coisas de aplicações open source e banco de dados.
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/
|
