Utilizando o phpDocumentor

Muitas pessoas ja baixaram e tentaram utilizar o phpDocumentor, correto? Porem muitas desistem achando que é um bixo de 7 cabeças, mas ao contrario, é muito simples. Neste post vou tentar explicar como funciona.

O phpDocumentor, alem de criar a documentação automaticamente,força o desenvolvedor documentar seu código, ficando mais legivel e amigavel.

Primeiramente vamos baixar o phpDocumentor em http://www.phpdoc.org/. Baixamos os arquivos, descompactamos em um diretório qualquer e não se preocupe com a quantidade de arquivos que o phpDocumentor possui, muitos deles são templates, exemplos, e documentação.

Com os arquivos prontos para serem editados, iniciamos editando o arquivo phpdoc.bat. Nele precisamos dizer onde está nosso php.exe logo no inicio do aruqivo, no meu caso, ele se encontra em C:\php-gtk2\php.exe.

SET phpCli=C:\php-gtk2\php.exe

No diretório user, temos os nossos projetos que serão documentados. Criamos um arquivo novo chamado nosso_projeto.ini e colocamos as seguintes configurações:

http://pastebin.com/f38420e50

; Diretório onde será salvo a documentação
target = D:/docs/

; Titulo dos documentos
title = Teste's Class

; Ignora arquivos ocultos
hidden = false

; Documentar elementos privados
parseprivate = off

; Iniciar a sequencia com uma pequena descrição
javadocdesc = off

; Tags customizadas (não consegui fazer funcionar, se alguem conseguir, comente ai)
;customtags = changelog

; Nome do pacote principal
defaultpackagename = Teste

; Arquivos à documentar (separados por virgula)
;filename = D:\www\teste\teste1.class.php, D:\www\teste\teste2.class.php

; Diretório à documentar
;directory = D:\www\teste\

; Ignora arquivos
ignore = templates_c/,*HTML/default/*,spec/

; Seta o template da documentação
; Aqui exitem varios templates, o legal é ver qual vc mais gosta, e seta-lo
; É possivel desenvolver templates próprios com o Smarty, muito show
; Alguns templates padrões:
;     HTML:frames:default
;     HTML:frames:l0l33t
;     HTML:frames:phpdoc.de
;     HTML:frames:phphtmllib
;     HTML:frames:phpedit
;     HTML:frames:DOM/default
;     HTML:frames:DOM/l0l33t
;     HTML:frames:DOM/phpdoc.de
;     HTML:Smarty:default
;     HTML:Smarty:PHP
;     PDF:default:default
;     CHM:default:default
;     XML:DocBook:default
output=HTML:Smarty:PHP

; Mudar a cor dos fontes (highlight)
sourcecode = on

No site e nos arquivos que você baixou, existe a documentação, é bem simples, e facil entender. Um exemplo simples de um método documentado, segue abaixo:

http://pastebin.com/f1ae9b100

/** 
 * Método que move os registros do resultset
 * 
 * < ?php 
 * 	$objDB = new MYSQL($servidor, $usuario, $senha, $banco);
 * 	$result = $objDB->Execute('select * from users');
 * 	$result->MoveNext();
 * ?>
 * 
 * @access   public
 * @name     MoveNext
 * @since    0.1 ~ 0.2
 */
public function MoveNext() {
	if(!$this->Fields = mysql_fetch_array($this->__resultSet)) {
		$this->EOF = FALSE;
	} else {
		for($i=0; $i__resultSet); $i++) {

			$this->Fields[$i] = str_replace('\"', '"', $this->Fields[$i]);
			$this->Fields[$i] = str_replace("\'", "'", $this->Fields[$i]);
			$this->Fields[$i] = str_replace('\%', '%', str_replace('%', '%%', $this->Fields[$i]));
			
		}
		$this->EOF = TRUE;
	}
} // MoveNext

Após documentar seu código, de 2 cliques no phpdoc.bat, aparecerá uma lista de documetações à gerar (os arquivos .ini), selecione o que voce deseja criar, e corra para o abraçoooo =D

Esta documentação ficará assim: