+5

Usando o PhpDoc

criado por Rodrigo Rodrigues em 03/12/2004 7:01pm
O PhpDoc foi baseado no JavaDoc da Sun onde seu objetivo principal é documentar sistemas através de comentários padronizados(tags especiais) dentro do próprio código.

O PhpDoc lê o código e procura os comentários padronizados(tags especiais) para depois gerar a documentação em diferentes formatos(layouts variados, pdf, xml, chm entre outros).

Tags especiais são palavras especiais que começam com o caracter "@" na frente dentro do comentário, são através delas que o PhpDoc gera a documentação.

Os comentários devem seguir alguns padrões para que o PhpDoc possa gerar a documentação, veja alguns exemplos:
<?
/**
* Aqui fica meus comentários
* @author Rodrigo Corinthiano Maloqueiro e Sofredor <rodrigo.coringao@gmail.com>
* @access public
*/
class Corinthians {
}
?>
Os comentários começam com "/**" e terminam com "*/".
O caracter "@" significa que é uma tag especial do PhpDoc.

Exemplo com mais comentários:
<?php
/**
* Esta classe é a responsável pela conexão com o banco de dados.
* @author Rodrigo Rodrigues <rsantos@gelre.com.br>
* @version 0.1
* @copyright Copyright © 2002, Rodrigo Corinthians S/A.
* @access public
* @package Infra_Estrutura
* @subpackage Conexao
*/
class Conexao {
    /**
    * Variável recebe o Host do banco.
    * @access private
    * @name $local
    */
    var $local;
	
    /**
    * Variável recebe o Usuário de acesso.
    * @access private
    * @name $usuario
    */
    var $usuario;
	
    /**
    * Variável recebe a Senha de acesso.
    * @access private
    * @name $senha
    */
    var $senha;
	
    /**
    * Variável recebe a conexão aberta.
    * @access private
    * @name $conn
    */
    var $conn;

    /**
    * Função construtora para setar os valores de conexão com o banco.
    * @author Rodrigo Rodrigues <rsantos@gelre.com.br>
    * @access public
    * @return void
    */
    function Conexao() {
    }
	
    /**
    * Função onde estabelece uma conexão com o banco.
    * @access public
    * @return Connection Retorna a conexão com o banco.
    */
    function getConexao() {
    }
	
    /**
    * Função para fechar a conexão com o banco.
    * @access public
    * @return void
    */
    function close() {
    }
}
?>

<?php
/**
* Esta classe é a responsável pela configuração do sistema.
* @author Rodrigo Rodrigues <rsantos@gelre.com.br>
* @version 0.1
* @copyright Copyright © 2002, Rodrigo Corinthians S/A.
* @access protected
* @package Infra_Estrutura
*/
class Config {
    /**
    * Variável recebe o diretório onde se encontra o sistema.
    * @access public
    * @name $pathDir
    */
    var $pathDir;

    /**
    * Função construtora para configurar o sistema.
    * @author Rodrigo Corinthiano e Maloqueiro <rsantos@gelre.com.br>
    * @access protected
    * @return void
    */
    function Config() {
    }
}
?>

<?php
/**
* Esta classe é a responsável pela integração com o Smarty Templates.
* 
* TesteExemplo:
* <?php 
* $smarty = new Smarty(); // Instância.
* ?>
* 
* @author Rodrigo Rodrigues <rsantos@gelre.com.br> * @version 0.2 * @copyright Copyright © 2004, Rodrigo Corinthians S/A. * @access public * @package Infra_Estrutura * @subpackage Smarty * @example Classe Smarty. */ class Smarty { /** * Variável recebe o diretório onde se encontra os templates. * @access private * @name $templateDir */ var $templateDir; /** * Variável recebe o diretório onde se encontra os templates compilados. * @access private * @name $templateDirCompile */ var $templateDirCompile; /** * Variável recebe o diretório para cache dos templates. * @access private * @name $cacheDir */ var $cacheDir; /** * Variável recebe o diretório onde se encontra as configurações dos templates. * @access private * @name $configDir */ var $configDir; /** * Função construtora para integrar com o Smarty Templates; * @access public * @return Smarty Retorna o objeto Smarty. */ function Smarty() { } /** * Função para montar um combo de usuários. * @access public * @param int[] $idUsuario Array com os Id's do usuários. * @param String[] $nomeUsuario Array com os Nomes dos usuários. * @return void */ function comboUsuario($idUsuario, $nomeUsuario) { } /** * Função para montar um combo de usuários. * @access public * @param int[] $idUsuario Id do usuário. * @param String[] $idPermissao Array com os Id's que o usuário tem permissão. * @return void */ function comboPermissaoUsuario($idUsuario, $idPermissao) { } } ?>

Descrição de algumas tags:
@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.

@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.

@return = Específica o tipo de retorno.

@subpackage = Específica o nome do pacote filho.

@version = Específica a versão da classe/função.

Caso queiram conhecer mais tags consulte o manual do site.


Instalação
Baixe a última versão "1.3.0rc3" do PhpDoc no site(http://sourceforge.net/project/showfiles.php?group_id=11194), depois descompacte o zip e crie um diretório chamado "phpdocumentor" no seu server e jogue os arquivos descompactados nele.

Acesse no browser a página(http://localhost/phpdocumentor/index.php), ela usa frames.

No frame de baixo tem um campo chamado "Working Directory", coloque o caminho "do diretório" do seu sistema que pretende gerar a documentação, lembrando que para funcionar você precisa ter os padrões de comentários nos códigos.

Na aba "Files" campos "Files to parse" e "Directory to parse" você coloca o mesmo caminho do diretório do seu sistema, o campo "Files to ignore" você coloca o caminho do arquivo ou diretório que deseja ignorar na geração da documentação.

Na aba "Output" campo "Target" você coloca o caminho onde ficará a documentação(aconselho colocar num diretório vazio, porque a documentação gera vários arquivos), no campo "Output Format" você escolhe na combo o tipo da sua documentação, depois de escolhido clica em "Add the converter in the help box".

Na aba "Options" campo "Generated Documentation Title" você coloca o título da sua documentação.

Por último no frame de baixo você clica no botão "create" ou "create(new window)".


O PhpDoc irá ler os comentários dos códigos do sistema e apartir disto irá gerar a documentação no formato escolhido.

Referências
Site oficial: http://phpdoc.org/
Download: http://sourceforge.net/project/showfiles.php?group_id=11194
Manual: http://phpdoc.org/manual.php

Sem mais, Rodrigo.

Comentários:

Mostrando 1 - 6 de 6 comentários
Fred Hakamine disse:
fiz tudo certinho... deu este erro: Cannot re-assign $this in c:\vertrigoserv\Apache\htdocs\phpDoc\phpDocumentor\ParserElements.inc on line 238
20/10/2005 6:25am (~19 anos atrás)

Coloquei no codigo assim:


/**
* Array de propriedades
* @name $arrHTMLProperties
* @var array
*/
protected $arrHTMLProperties = array();


mas na saida (em "Source for file myFile.php")

fica assim

protected $arrHTMLProperties = array();


ou seja, sem nenhum comentario!


pq?
12/03/2005 12:41pm (~20 anos atrás)

Mas quando executei tudo isso não encontrei nada além de arquivos .css no "outuput" que eu havia informado!

Como faço para verificar a documentação que eu fiz?
Obrigado!
03/03/2005 3:07pm (~20 anos atrás)

Robson Mello disse:
Muitas vezes o comentário bem estruturado poupa muito tempo de reajustes em um sistema, vale a pena investir em documentação e realmente o php doc é uma solução muito boa para documentação de projeto.
26/01/2005 6:43am (~20 anos atrás)

Muito bom o teu artigo estas de parabén
24/01/2005 10:10pm (~20 anos atrás)

DDDD disse:
Cara voce tirou a minha duvida, eu procuro isto a muito tempo e nao acho.

Que pena que tem umas pessoas aqui que me criticam de uma olhada nos comentarios do Uso da Inteligencia que ta na pagina principal
08/12/2004 12:32pm (~20 anos atrás)

Novo Comentário:

(Você pode usar tags como <b>, <i> ou <code>. URLs serão convertidas para links automaticamente.)