9

Nesses dias ando mexendo bastaste em arquivos de frameworks, projetos, etc...e estou vendo varias coisas que nunca vi, uma delas é o tal do PHPDoc (consegui o nome graças a minha IDE), mas pesquisando aprendi muito pouco sobre!

Exemplo:

class Foo {
    /**
     * Constructor
     * 
     * @param string $string
     * @return string
     */
    public function __construct($string){
        return $string;
    }
}

Agora as perguntas:

  • O que é PHPDoc?

  • Qual sua utilidade?

  • Como usar?

  • Tem alguma regra, recomendação do PSR sobre isso? Se sim, qual?

2
  • 1
    Qual a diferença entre tipos de comentários em PHP?
    – rray
    Commented 7/03/2016 às 12:01
  • Tem os comentário normais da linguagem. De linha, via o caracter # ou //. De múltiplas linhas /* igual ao do C . E aqueles com semântica que começam com /** interpretados por pré processadores como o PHPDOC, Doctrine.
    – cavila
    Commented 23/10/2023 às 12:56

3 Respostas 3

12

O que é PHPDoc?

Para não confundir aqui vou usar o termo DockBlock alguns vão chamar de doclet ou PHPDoc, isso não importa, o que é importante é diferenciar o PHPDoc comentário do PHPDoc ferramenta.

O PHPDoc ferramenta gera documentação automaticamente com base no código e em comentários DockBlock. Porém você pode usar outras ferramentas para gerar essa documentação, eu particularmente prefiro o ApiGen.

O DockBlock começa com /** , eles tem origem no javadoc e podem (ou não) ter uma infinidades de tags que começam com @;

Qual sua utilidade?

Docblocks são um meio de comunicação entre quem faz o código e quem o consome. Quando você passa seu código para terceiros, ou obtêm um código essa documentação vai ajudar no entendimento, uso e modificação do mesmo.

Eles servem de base para gerar uma documentação objetiva que pode abordar uma série de questões comuns a quem consome o código.

Posso utilizar livremente o código em meus projetos? (@license); Quem é o autor do código? (@author); O que essa função retorna? (@return); etc;

Essas tags se comunicam bem com a máquina elas ajudam o IDE a entender o código, no site do PHPDoc existe uma lista de tags são suportadas pelas ferramentas de geração de documentação.

Existem também frameworks como o Doctrine e PHPUnit que aceitam suas próprias tags nesses comentários. Com elas é possível, por exemplo, mapear e gerar todo o banco de dados ou entidades de uma aplicação com o Doctrine mas esse uso já foge da questão de documentação.

Como usar?

Dentro da filosofia de Robert C. Martin a regra básica que recomendo é: coloque o mínimo possível de comentários mas o suficiente para ser claro.

A exceção é se você vai disponibilizar o código publicamente então - a exemplo dos sistemas open sources mais comuns em PHP - quanto mais explicado melhor, fora este caso raramente vale a energia documentar muito.

Lembre-se que você vai ter manter os comentários coerentes com o código, é muito comum o código ser refatorado e os comentários passarem informações erradas por estarem defasados, por isso muitos consideram comentários como um tipo de duplicação de código.

Qualquer código, função, variável, classe, devem ser claros o suficientes para entendermos o eles fazem e são dentro do seu contexto, sem precisarmos de nenhum comentário explicando.

Quando não atingimos esse ideal um comentário é bem-vindo. Ele pode ser um alerta, esclarecimento ou explicação. Mas esses comentários são sempre fracassos da nossa capacidade de se expressar através do código.

Quando necessário ele deve ser preciso e claro para não confundir, um comentário ruim mais atrapalha do que ajuda.

Existem muitas tags no padrão phpdoc, mas não considero que seja ideal manter a maioria dessas informações em um DocBlock, quando estão nele costumam ser apenas firulas. Autoria, versão, modificação, por exemplo ficam melhor em um sistema de controle versão. Outros exemplos de comentários ruins são aqueles óbvios ou redundantes em relação ao código, são apenas poluição.

Exemplo de documentação inútil:

/**
* Entidade Usuário
*/
class user {
    /**
    * nome do usuário
    */
    $nome;

    //...

    /**
     *Estabelece o Nome do usuário
     */
    function setName(){//... }

    /**
     *Pega o Nome do usuário
     */
    function getName(){//... }

    // … 

}

O que vale a pena documentar normalmente são os tipos retornados pelas funções, tipos das variáveis, e tipos dos parâmetros. Mesmo assim só documente quando não é possível a indução (Com PHP 7 a necessidade de documentação deve diminuir). Isso facilita bastante a vida.

Tem alguma regra, recomendação do PSR sobre isso? Se sim, qual?

A regras de apresentação do código na PSR-2 se aplicam a DocBlocks, fora isso existe apenas um rascunho em desenvolvimento que poderá vir a ser uma recomendação no futuro. Pode ser lido aqui: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md

5

PHPDoc é uma forma de adicionar informações sobre uma estrutura(méotodo ou classe etc) elas são úteis para algumas ferramentas que geram documentação automaticamente apartir desses 'comentários'. Essas informações são importantes para IDE com elas suas classes entram no auto-complete então é fácil ir navegando de um método a outro.

Para usar o doclet é quase igual a um comentário o fato importante é que após a barra são necessarios dois asteriscos do consecutivos.

/** doclet
/* comentário
0
2

O PHPDoc foi baseado no JAVADoc da Sun e tem como objetivo padronizar a documentação de códigos PHP. Ele lê o código e analisa gramaticalmente procurando por tags especiais. A partir delas extrai toda documentação usando diferentes formatos (pdf, xml, html, chm Windows help e outros). Todas as tags especiais são escritas dentro do comentários do php /*comentários */ e necessariamente começam com o @ (arroba).

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 Ignora código  
@internal Documenta função interna do código  
@link Link do código  
@see Define uma referência a outro elemento ou uma URI  
@since Define a partir de qual versão os elementos estruturais foram disponibilizados  
@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.  

Para gerar a documentação, pode-se instalar a ferramenta utilizando PEAR, Composer ou download manual.

Referências:
Linha de Codigo
PHPDoc

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .