PHPDoc: Como usar

PHPDoc: O que é e como usar?

Posted by

Se trabalhas ou trabalhas-te com PHP, certamente já te cruzas-te com o PHPDoc. Muitas vezes é algo chato de fazer, mas é uma mais valia. Esta mais valia aumenta o seu valor, quando temos projetos extensões, com muitos ficheiros e linhas de código.

Vamos então perceber o que é o PHPDoc, e em que nos pode ajudar durante e depois do desenvolvimento.

O que é o PHPDoc?

O PHPDoc ou PHPDocumentator, é uma ferramenta baseada no JAVADoc que tem como objetivo padronizar a documentação dos códigos PHP. Esta ferramenta lê todo o código do projeto, procurando por tags expecificas e a partir destas, pode gerar documentação em vários formatos.

Essas tags são adicionadas dentro de comentários em PHP, e é necessário que todas elas sejam iniciadas por @:

Esta documentação que fica dentro do comentário, é chamada de DocBlock.

Para que serve?

Para mim esta ferramenta tem dois objetivos principais (dentre outros):

O primeiro é que a documentação em PHPDoc, vai facilitar a passagem do código a terceiros. Não apenas a terceiros, mas mesmo dentro da equipa, ou equipas do mesmo projeto.

Vamos imaginar o seguinte cenário. Existe um MVP (Produto Mínimo Viável), que depois de desenvolvido, é entregue a uma outra equipa que irá continuar ou integrar o mesmo dentro doutro sistema. Assim que a nova equipa recebe o MVP, e começa o novo desenvolvimento sobre esta base, necessitará de entender o mesmo.
Tendo esta documentação disponível, é mais prático iniciar um teste ou desenvolvimento.

O segundo ponto, é que permite também ao IDE, e extensões em uso no mesmo, que consigam ler o código e transmitir a informação de classes e método de forma mais prática. Isto economiza tempo, e permite uma fluidez bem maior no desenvolvimento.

Como usar?

“Coloque o mínimo possível de comentários, mas o suficiente para ser claro.”

Robert C. Martin

Numa opinião profissional e própria, deve sempre existir documentação. Existem algumas excepções, mas estas devem ser pontuais ou passaram rapidamente a regras.

Se estivermos a desenvolver um projeto pessoal, que apenas nós iremos ter acesso, basta manter algumas notas pontuais durante o projeto, para coisas especificas. Quando entramos em projetos mais complexos, com equipas maiores, deve ser mantido uma documentação limpa e coerente. Isto também deve ser regra, quando disponibilizamos o código a terceiros, como é o caso de projetos open source.

Um exemplo básico de uma documentação mínima, é deixar uma breve descrição desse método, parâmetros do método, os seus tipos e o retorno:

Algumas tags especiais:

  • @access – Especifica o tipo de acesso (public, protected e private). 
  • @author – Especifica o autor do código/classe/método. 
  • @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 nome/alcunha (alias). 
  • @package – Especifica o nome do pacote pai, isto ajuda na organização das classes. 
  • @param – Especifica os parâmetros (muito usado em métodos). 
  • @return – Especifica o tipo de retorno (muito usado em métodos), presente no exemplo acima. 
  • @subpackage –  Especifica o nome do pacote filho. 
  • @version – Especifica a versão da classe/método. 

Comentários

comentarios