Documentando seu fonte PHP com comentários

Todos os blocos de documentação são um comentário no estilo C com dois asteriscos após a barra, como mostrado abaixo:

/**  
 *
 */

Todos os outros comentários são ignorados pelo interpretador da documentação. Note que mesmo sendo quase toda a documentação escrita em texto puro, existem alguns caracteres "@" flutuando pelo código fonte. Este símbolo é usado como um comando especial para o interpretador, e é chamado de tag. Se o símbolo esta no início da linha, é uma tag padrão, se esta contido em {chaves}, é uma tag inline.

/**
 * {@inlinetag}
 * esta @não é uma tag padrão - deve iniciar uma linha.
 * isto é valido também {@inlinetag}
 * @tagpadrão
 */

Documentando variáveis globais

Veja este exemplo de código:

/**
 * Bloco de documentação especial para variáveis globais
 * @global integer $GLOBALS['_myvar']
 * @name $_myvar
 */ 
$GLOBALS['_myvar'] = 6;

Neste segmento, você pode ver duas tags importantes ao documentar variáveis globais. A tag $global é usada para indicar ao interpretador como encontrar a declaração de uma variável global. Sem esta tag, não será gerada documentação para $_myvar. A tag @global pode ter várias formas - tenha certeza de especificar o tipo e o nome global, sem descrição, ou o interpretador irá gerar um aviso e falhar na interpretação da variável global. Avisos de bloco de documentação a nível de pagina

A questão única mais perguntada sobre a utilização de tags no phpDocumentor envolve avisos de documentação a nível de pagina. Esta seção irá responder a quaisquer questões sobre esse aviso de uma vez por todas.

phpDocumentor organiza os elementos de procedimentos e classes em grupos especiais chamados pacotes. Em versões anteriores do phpDocumentor, se um pacote não foi especificado explicitamente usando a tag @package, o programa faria uma adivinhação educada de qual pacote um elemento do fonte pertenceria.

Tempos após, se tornou aparente que em vários casos, elementos do fonte forram incorretamente agrupados em um pacote devido ao trabalho de adivinhação que o phpDocumentor usa. Finalmente foi tomada a decisão de requerer explicitamente a tag @package, e de gerar um aviso sempre que esta tag estivesse faltando no elemento superior do código fonte.

A maior confusão vem da documentação de arquivos. O phpDocumentor documenta todos os elementos do fonte lendo o bloco de documentação que esta imediatamente antes do elemento, assim:

<?php   
/**
 * Documenta a classe a seguir
 * @package SomePackage
 */
class SomeClass {
}
?>

phpDocumentor também pode documentar o conteúdo de um arquivo. Mas como um bloco de documentação pode vir imediatamente antes do arquivo que ele contém? A resposta fácil é assumir que o primeiro bloco de documentação em um arquivo documenta o arquivo que o contém, isso funciona bem, mas pode ser decepcionante:

<?php
/**
 * Documenta a classe a seguir ou o arquivo?
 * @package SomePackage
 */
class SomeClass {
}
?>

Este exemplo mostra a ambiguidade, este bloco de documentação documenta a classe ou o arquivo? Para resolver esta ambiguidade, o phpDocumentor usa um simples algorítimo para tomar a sua decisão. Se o primeiro bloco de documentação contém uma tag @package ele documenta o arquivo, a menos que ele preceda uma declaração de classe. Se o primeiro bloco de documentação precede outro bloco de documentação, ele documenta o arquivo.

<?php
/**
 * Este é um bloco de documentação a nível de arquivo
 * 
 * Será emitido um aviso, dizendo para documentar o define, use
 * um novo bloco de documentação
 * @package SomePackage
 */
define('foo', 'bar');
?>
 
<?php
/**
 * Este não é um bloco de documentação a nível de arquivo
 * 
 * Um aviso será emitido, dizendo que não há um bloco de documentação a nível de arquivo
 * e que este bloco de documentação será usado para o comando define
 */
define('foo', 'bar');
?>
 
<?php
/**
 * Este não é um bloco de documentação a nível de arquivo 
 *
 * Um aviso será emitido, dizendo que não há um bloco de documentação a nível de arquivo
 * e que este bloco de documentação será usado para a classe
 */
class foo {}
?>
 
<?php
/**
 * Este não é um bloco de documentação a nível de arquivo, porque ele precede uma declaração de classe
 * 
 * um aviso será emitido, dizendo que não há um bloco de documentação a nível de arquivo
 * e que este bloco de documentação será usado para a classe
 *@package SomePackage
 */
class foo {}
?>
 
<?php
/**
 * Este é um bloco de documentação a nível de arquivo
 * 
 * Um aviso será emitido dizendo que foi assumido como pacote
 * AlgumPacote
 */
/**
 * Este é um bloco de documentação de classe normal
 * 
 * Este bloco de documentação será para a classe
 *@package AlgumPacote
 */
class foo {}
?>
 
<?php
/**
 * Este é um bloco de documentação de nível de arquivo
 * 
 * Um aviso será emitido dizendo que o pacote foi assumido como sendo
 * AlgumPacote porque não foi usada a tag @package
 */
/**
 * Este não é um bloco de documentação a nível de arquivo, porque precede uma declaração de classe
 *
 * Um aviso será emitido, dizendo que não há bloco de documentação a nível de arquivo
 * e este bloco de documentação será para a classe
 * @package AlgumPacote
 */
class foo {}
?>
 
<?php
/**
 * Este é um bloco de documentação a nível de arquivo
 * 
 * Não será emitido aviso. Esta é a utilização recomendada
 *@package AlgumPacote
 */
/**
 * Este não é um bloco de documentação a nível de arquivo, porque ele precede uma declaração de classe
 *
 * Isto também é a utilização recomendada
 * @package AlgumPacote
 */
class foo {}
?>