Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.
Aqui estão todas as tags, ainda preciso descrever melhor algumas delas, assim como pretendo logo colocar exemplo em todas.
Esta é uma lista das tags e o que elas descrevem:
@abstract
Use a tag @abstract para declarar um método, variável de classe, ou classe que deva ser redefinida em uma classe filho para ser válida.
@access
Controla o acesso ao próximo elemento. Se @access é private, o elemento não será documentado a menos que a opção de linha de comando --parseprivate seja especificada.
@author
A tag @author é usada para documentar o autor de qualquer elemento que possa ser documentado. O phpDocumentor irá pegar qualquer texto entre maior que e menor que (< and >) e tentar interpretar como um endereço de email criando um link na pagina para enviar email, exemplo:
/** *@author Fernando Conceição <conceicao.fernando@gmail.com> */
@category
A tag @category é usada para organizar grupos de pacotes juntos. Isto é diretamente aplicável ao conversor XML:DocBook/peardoc2 e pode ser usado pelos outros conversores. Outros conversores embutidos no phpDocumentor ignoram a categoria, mas isso pode mudar em versões futuras. Também é possível especificar dinamicamente a categoria usando a opção de linha de comando -dn, --defaultcategoryname
@copyright
A tag @copyright é usada para documentar as informações de direitos autorais de qualquer elemento que possa ser documentado. O phpDocumentor irá exibir o conteúdo desta tag sem nenhuma alteração.
@deprecated
A tag @deprecated é usada para informar a versão que um elemento se tornou obsoleto ou outra informação para todos os elementos que podem ser documentado com exceção de uma pagina. Se presente, o texto da tag será exibido sem nenhuma alteração. Use @deprecated para informar aos usuários de elementos que forem obsoletos e que não devem mais ser usados.
@example
A tag @example pode ser usada para interpretar um arquivos de exemplo com destaque de cores e links para a documentação. Esta tag versátil tenta ler o arquivo completo especificado, e irá aceitar qualquer caminho que a função fopen aceite. O phpDocumentor confere se o arquivo tem uma extensão .php válida como definido no arquivo .ini do phpDocumentor e então abre o arquivo. Ele irá interpretar o arquivo, e mostrar o fonte com destaque de cores com números de linha, links para a documentação e irá adicionar na documentação um link para este arquivo.
Se for dado um caminho absoluto, o phpDocumentor não irá procurar pelo exemplo em mais nenhum local. Se for dado um caminho relativo, o phpDocumentor procura pelo arquivo de exemplo primeiro no diretório especificado pela opção da linha de comando -ed, --examplesdir se presente. Após irá procurar no subdiretório examples do arquivo atual. Se não, ele irá procurar por um subdiretório chamado examples no diretório superior da interpretação, e se não encontrado, no diretório superior.
A tag @filesource serve para um fim similar, mas ao invés de interpretar um arquivo separado, ele interpreta o fonte do arquivo atual.
* * @final
Indica que o método da classe não deve ser sobrescrito por uma classe filha
@filesource
A tag @filesource só pode ser usada em um bloco de documentação de arquivo, ela será ignorada em qualquer outro local. O phpDocumentor interpreta o arquivo atual, e coloca o código fonte dele com destaque de cor e linhas numeradas, cria links para a documentação e então adiciona um link para o arquivo gerado na documentação.
@global
@global tipodedados $nomedavariavelglobal
@global tipodedados definição
Documenta uma variável global, ou o seu uso em uma função/método. Já que não existe um meio padrão de declarar variáveis globais, o phpDocumentor requer que a tag @global seja usada em um bloco de documentação precedendo a definição da variável global. Para suportar a utilização anterior de @global, existe uma sintaxe alternativa que suporta blocos de documentação precedendo a declaração da função, usado para documentar a utilização de variáveis globais. Em outras palavras, existem duas utilizações de @global: definição e utilização em função.
O phpDocumentor não irá tentar interpretar automaticamente qualquer variável global. Apenas uma tag @global é permitida para um bloco de documentação para uma variável global. Um bloco de documentação para uma variável global deve ser seguido pela definição da variável global antes que qualquer outro elemento ou bloco de documentação ocorra, ou será emitido um aviso.
tipodedados deve ser um tipo válido no PHP ou "mixed"
$nomedavariavelglobal deve ser o nome EXATO da variável global tal qual declarado no fonte (use @name para mudar o nome exibido na documentação).
A sintaxe de função/método é usada para documentar a utilização de uma variável global em uma função, e NÃO deve ter um $ começando a terceira palavra. O tipo de dados será ignorado se já houver uma variável global com o mesmo nome documentada no projeto. O phpdocumentor irá procurar se o tipo é o nome de uma classe que tenha sido interpretada, se for, irá criar um link para esta classe em vez de apenas mostrar o tipo. O phpDocumentor irá exibir a descrição opcional sem nenhuma modificação.
/**
* Exemplo de uma declaração incorreta de @global
* @global bool $GLOBALS['baz']
* @author blahblah
* @version -6
*/
include("file.ext");
// erro - elemento encontrado antes da declaração da variável global, o bloco de documentação irá se aplicar ao include
$GLOBALS['baz'] = array('foo','bar');
/** Exemplo de uma declaração incorreta de @global
* @global parserElement $_Element
*/
/**
* erro - este bloco de documentação ocorre antes da definição da variável global e será aplicado a função,
* ignorando a variável global completamente
* /
$_Element = new parserElement;
function oopsie()
{
}
/** Exemplo de uma declaração correta de @global,
* mesmo com várias coisas irrelevantes no meio
* @global mixed $_GLOBALS["myvar"]
*/
// this is OK
if ($pre)
{
$thisstuff = 'is fine too';
}
$_GLOBALS["myvar"] = array( "this" => 'works just fine');
/**
* Exemplo de utilização de @name com @global
* A tag @name *deve* ter um $ no nome, ou um erro será emitido
* @global array $GLOBALS['neato']
* @name $neato
*/
$GLOBALS['neato'] = 'This variable\'s name is documented as $neato, and not as $GLOBALS[\'neato\']';Aqui um exemplo de documentar o uso de uma variável global em uma função/método:
/**
* Used to showcase linking feature of function @global
*/
class test
{
}
/**
* @global test $GLOBALS['baz']
* @name $bar
*/
$GLOBALS['bar'] = new test
/**
* example of basic @global usage in a function
* assume global variables "$foo" and "$bar" are already documented
* @global bool used to control the weather
* @global test used to calculate the division tables
* @param bool $baz
* @return mixed
*/
function function1($baz)
{
global $foo,$bar;
// note that this also works as:
// global $foo;
// global $bar;
if ($baz)
{
$a = 5;
} else
{
$a = array(1,4);
}
return $a;
}@ignore
Indica que o próximo elemento não deve ser documentado
@internal
Adiciona uma informação apenas para o piblico interno. A idéia desta tag é poder fazer dois conjuntos de documentação, um para o publico e uma documentação mais "interna". A informação colocada nesta tag só esta disponível se quando a documentação for criada seja usada a opção de linha de comando -pp ou --parseprivate .
@license
@licence Endereço Licença
Exibe um link para a licença do elemento. Endereço é a url para a licença do elemento e Licença é o nome da licença pare este elemento.
@link
@link url texto
Cria um link para outro endereço, usado por exemplo, para criar um link para uma documentação externa ao seu projeto.
@method
Método magico de uma classe.
@name
Define o nome que uma variável global vai ser exibido. Veja os detalhes e um exemplo em @global
@package
Define o nome do pacote a qual o elemento pertence
@param
@param tipodedados $nomedoparametro descrição
Documenta o parâmetro de uma função, use uma tags destas para cada parâmetro, na ordem que estejam na função. tipodedados é qualquer tipo de dados do php ou "mixed". $nomedoparametro é simplesmente o nome dele na função, e descrição é a descrição de sua utilidade.
@property
Define uma propriedade magica de uma classe. Por propriedade magica entenda como uma propriedade que não esta explicitamente definida na classe, mas existe quando você esta usando os métodos _get e _set para criar propriedades que não estejam definidas.
@return
@return tipodedados descrição
Define o valor que uma função/método retorna. tipodedados é o tipo do retorno e descrição é para indicar o que é retornado. Esta tag também pode ser usada como @returns para compatibilidade com outros sistemas de documentação.
@see
Cria um link para a documentação de um elemento
@since
Indica que um elemento esta disponível em um pacote a partir da versão indicada.
@static
Indica que um elemento é estático, que pode ser utilizado sem a criação de um objeto da classe, por exemplo class::função()
@subpackage
Define um subpacote dentro de um pacote.
@todo
Define um item a ser feito depois, por exemplo, você esta fazendo uma função e quer se lembrar que ela esta incompleta ou que precisa ser melhorada.
@tutorial
Exibe um link para documentação externa
@uses
Cria um link para a documentação das funções e dela para aqui. A ideia é assim, você indica que este elemento utiliza outra classe/função, então é criado um link para este outro elemento. Neste outro elemento é criado um link para aqui indicando que este elemento se utiliza do outro.
@var
@var tipo desc
Documenta o tipo de uma variável de classe.
@version
Documenta a versão do elemento