PHPDoc é uma convenção de comentários estruturados para PHP. Usada logo antes de classes, funções, métodos, propriedades e constantes para descrever seu comportamento, tipos e propósito.
Exemplo básico:
/**
* Soma dois números.
*
* @param int $a Primeiro número
* @param int $b Segundo número
* @return int Resultado da soma
*/
function soma($a, $b) {
return $a + $b;
}Tags disponiveis:
| @access | acesso |
| @api | api |
| @author | autor |
| @copyright | direito autoral |
| @deprecated | descontinuado |
| @example | exemplo |
| @generated | gerado |
| @ignore | ignorar |
| @internal | interno |
| @link | link |
| @method | metodo |
| @package | pacote |
| @param | parametro |
| @property | propriedade |
| @return | retorna |
| @see | Vejo |
| @since | Desde a |
| @throws | arremessa |
| @todo | pendência |
| @uses | usa |
| @var | variavel |
| @version | versão |
Aqui estão as mais usadas na prática, com exemplos e quando usar:
| Tag | Quando Usar | Exemplo |
|---|---|---|
@param |
Antes de cada parâmetro de função/método | @param string $nome Nome do usuário |
@return |
Descreve o que a função retorna | @return bool Verdadeiro se válido |
@var |
Declara tipo de uma propriedade ou variável | @var int |
@throws |
Quando a função pode lançar uma exceção | @throws InvalidArgumentException |
@author |
Nome do autor do código | @author João |
@since |
Desde que versão existe | @since 1.0.0 |
@deprecated |
Se o código está obsoleto e será removido | @deprecated use outraFuncao() |
@see |
Referência relacionada | @see outraFuncao() |
@link |
Link para doc ou referência externa | @link https://exemplo.com/docs |
@todo |
Anotar tarefas pendentes | @todo otimizar desempenho |
@uses |
Quando outra função/classe é usada aqui | @uses TemplateManager::path() |
@example |
Mostrar exemplo de uso | @example examples/ex1.php |
@internal |
Esconde da documentação gerada (uso interno) | @internal |
Menos usadas:
-
@access:public,private,protected— já é desnecessária no PHP moderno, pois o acesso é declarado diretamente (public, etc.). -
@api: marca como parte da API pública (ex: SDK) -
@generated: normalmente usada por ferramentas automatizadas -
@ignore: oculta da documentação -
@package/@subpackage: usado em projetos grandes, geralmente junto com autoloaders (como Composer) -
@property: descreve propriedades mágicas (__get,__set) -
@method: descreve métodos mágicos (__call) ou dinâmicos -
@version: versão da classe ou biblioteca