Documentação de software com phpDocumentor.
Autor: Bruno A. Freitas | Publicado: 2013-07-19T05:39:00-07:00








Salve queridos irmãos,
hoje eu queria apresentar mais uma ferramenta que facilita e muito a
vida de um desenvolvedor e falar um pouco sobre documentação de
software.



1.0 Introdução a
Documentação.



Pra começar sei que é
do conhecimento de todos o tamanho da importância de se documentar
seus códigos, quanto mais quando se trata de grandes projetos, e não
é algo que tome muito do seu tempo pois é feito junto ao código e
ajuda em dores de cabeça futuras.



A documentação do
software nada mais é do que uma descrição de cada parte do
código-fonte, um método, uma classe, um atributo ou um trecho.
Podemos dizer que a documentação é um conjunto de manuais gerais e
técnicos que podem ser organizados na forma de textos e comentários,
e permite a criação de diagramas, fluxogramas, gráficos, etc...



2.0 phpDocumentor.



Bem pra facilitar nossa
vida tempos uma ferramenta chamada phpDocumentor, que faz a
documentação do seu código identificando os comentários de sua
aplicação PHP.



Aqui vai um pequeno
exemplo, mas vou deixar no fim do post alguns links que podem ajudar
a fazer a documentação da sua aplicação:



/**

&nbsp;* Breve exemplo metodo.

&nbsp;*

&nbsp;* @name Soma&nbsp;

&nbsp;* @param int $a O
primeiro parametro e sua descricao

&nbsp;* @param int $b O
segundo parametro e sua descricao

&nbsp;* @access public

&nbsp;* @return  Soma dos
parametros.

&nbsp;*/

&nbsp;public functions Soma( $a
, $b){



&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; return $a + $b;

&nbsp;


&nbsp;}



Na documentação o
phpDocmentor identifica o intervalo entre /** até */
e descreve os parâmetros e outras informações a partir dos
identificadores @param, @name dentre outros.



2.1 Download e
Instalação



Bem galera essa parte é
bem simples, não tem segredo.




Em primeiro lugar
 faça o download pelo site : http://www.phpdoc.org/
 .


Descompacte o
 arquivo na pasta do seu servidor. Ex: /var/www/ ou /xampp/htdocs/


De permissões as
 pastas se necessário.


Abra com o navegador
  o phpdoc.










Na parte inferior
 você vai ver um diretório apontando pra pasta do phpdoc, troque
 pela pasta da sua aplicação.


Na aba Files
 em Files parse e Directory to parse aponte para pasta
 de sua aplicação.










Ainda na aba Files
 em Files to ignore indique os arquivos que deseja que não
 sejam documentados. 
 


Na aba Output em
 Target aponte o
 diretório em que seseja salvar a documentação.










Em
 Output Format
 selecione o formato que deseja gerar a documetação.


Em
 opções adicione um titulo para sua documentação, indique o
 @package padrão do projeto e a categoria e click em Create ou
 Create ( new windows ). 
 











E
pronto, a documentação esta comcluida.



3.0
Dicas:



Acessem: http://trac.expressolivre.org/wiki/WF/PHPDoc

&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;http://blog.intermol.com.br/2008/03/23/como-documentar-seu-php-phpdocumentor/

&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;http://www.ricardo-vargas.com/pt/podcasts/documentation/








Bem
galera por enquanto isso é tudo, qualquer dica sugestão faça seu
comentário, é muito importante pra manter a qualidade no conteúdo,
se gostou divulgue e ajude a espalhar a palavra. Até Breve.