PHPDoc, quem nunca ouviu falar sobre documentação no PHP ou em outra linguagem. E claro já ouviram falar, pq aquele programador nao comentou isto ou aquilo, putz.. agora tenho que ficar lendo a loucura dele p/ tentar entender o que ele queria fazer desta função e tals. Bom para padronizar entao os seus códigos PHP achei na net alguns documentos sobre os comentários de código PHP e JAVAdoc onde ferramentas utilizam-se disto para gerar um documento sobre o seu código fonte.
E para começão devemos nos ater ao pequenos detalhes, primeiro que o comentário para isto deve estar em /** comentario */, não pode se esquecer dos dois asteriscos dps da barra, e claro a tag do comentário deve comecar sempre com um arroba (@).
Estas tag´s são padronizadas, entao nao invente de criar uma ou várias, o melhor é usar o que já fizeram que o seu programa vai ficar bem bonito.
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 Pode ser utilizada para realizar uma referência cruzada
para outra classe, interface, método, constructor, campo
ou URL:
* @since Desde o codigo foi feito - fundação
* @tutorial Um pequeno 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.
* @exception Utilizada para a declaração de métodos, construtores
e deveria consistir no nome da exceção seguida de
uma breve descrição sobre a circunstância em que a
exceção é lançada:
* |------> Exemplo : @exception RecordNotFound o registro
informado não foi localizado
*/
Exemplo parte de código documentado com PHPDoc.
/**
* Comentário de cabeçalho de arquivos
* Esta classe de pessoas
*
* @author Rafael Stoever
* @version 0.1
* @copyright GPL © 2006, rstoever.com
* @access public
* @package Production
* @subpackage Pessoa
* @example Classe Pessoa();
*/
class Pessoa {
/**
* Comentário de variáveis
* Variável privada que controlará o nome da pessoa.
* @access private
* @name $nome
*/
private $nome = "";
/**
* Construtor da classe
* @access public
* @param String $nome
* @return void
*/
puclic function __construct($strNome = "") {
$this->setNome($strNome);
}
/**
* Função para atribuir valor para o nome da pessoa
* @access public
* @param $strNome Variavel String que irá receber o nome da pessoa
* @return void
*/
public function setNome($strNome = "") {
if (empty($strNome)) $this->nome = "Anonimo"
else $this->nome = $strNome;
}
Fontes: www.phpdoc.org
pear.php.net/package/PHPDoc
sourceforge.net/projects/phpdoc/
-------------
E noutra hora explicarei como instalar o phpdoc na sua maquina para gerar esta documentação.
Fundamental e necessário, apesar de muitos programadores não gostar de documentar o código. Abraço!
Ótimo tópico, gostei mesmo.
Não entendo nada de documentação, mas ja gostei bastante disso. \o/