Usando o PhpDoc
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:
Os comentários começam com "/**" e terminam com "*/".
O caracter "@" significa que é uma tag especial do PhpDoc.
Exemplo com mais comentários:
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.
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 { } ?>
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. ** @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) { } } ?>* TesteExemplo: * <?php * $smarty = new Smarty(); // Instância. * ?> *
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.
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?
/**
* 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!
Como faço para verificar a documentação que eu fiz?
Obrigado!
03/03/2005 3:07pm
(~20 anos atrás)
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)
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
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)