PHPDoc, para que server e onde devo usar?

Olá pessoal, tudo bem?!

Com certa frequência menosprezamos o valor do PHPDoc, porém o que é isso?

‘”PHPDoc” is a section of documentation which provides information on aspects of a “Structural Element”.’

PHP Fig – PSr’5 – Definitions

“PHPDoc” é uma seção de documentação que fornece informações sobre aspectos de um “Elemento Estrutural”.

Sua falta se dá no pior momento, onde necessitamos consultar um recurso e não encontramos nada sobre o mesmo, apenas as várias linhas de sua implementação. Abaixo  pode-se observar um trecho de código sem o uso do PHPDoc.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<?php 

namespace Package\Subpackage;

class Zip
{
  private fileName;

  public function compress(SplFileInfo $file)
  {
    // Implementação do método para compressão...
  }
}

Sem a inclusão dos PHPDocs não será possível usufruir do recurso de autocomplete das IDE’s e quando o desenvolvedor acessar diretamente o código não encontrará a documentação necessária para consumir os recursos desejados, aumentando a complexidade de uso do mesmo.

O PHP Fig (recomendação de leitura: “PHP segue padrões SIM!!!“) tem em andamento o desenvolvimento da PSR-5, onde trazem as recomendações necessárias para implementar o PHPDoc,  vale salientar que o mesmo encontra-se em DRAFT podendo sofrer alterações.

Vamos implementar o PHPDoc no exemplo demonstrado acima, para classes, métodos e atributos dispomos como padrão três tags que, podem ser herdadas de subclasses, métodos ou atributos com mesmo nome, sendo elas:

• @version
  • Utilizada para denotar alguma descrição de “versioning” para um elemento.
• @author
  • Utilizada para documentar o autor de qualquer “Elemento Estrutural”.
• @copyright
  • Utilizada para documentar as informações de copyright de qualquer “elemento estrutural”.

Para classes dispomos:

• @package
  • Categoriza o elemento associado em um agrupamento ou subdivisão lógica.
• @subpackage
  • Categoriza o elemento associado em um agrupamento ou subdivisão lógica.

Para atributos/constantes dispomos:

• @var
  • Define que tipo de dados é representado por um valor de uma constante, propriedade ou variável.

Para métodos dispomos:

• @param
  • Documenta um único argumento de uma função ou método.
• @return
  • Documenta o valor de retorno de funções ou métodos.
• @throws
  • Indica se o elemento associado pode lançar um tipo específico de exceção.

Abaixo podemos observar nosso exemplo de código com o PHPDoc implementado.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<?php 

namespace Package\Subpackage;

/**
 * Class Zip
 *
 * Responsável por realizar a criação de um arquivo .zip conforme arquivo ou diretório informado.
 * 
 * @package    Package
 * @subpackage Subpackage
 * @author     Diego Brocanelli <diegod2@msn.com>
 * @version    1.0
 * @copyright  GLP-3
 */
class Zip
{
  /**
   * Responsável por identificar o arquivo ou diretório desejado ao qual será utilizado como base para a
   * criação do arquivo .zip
   * 
   * @var \SplFileInfo
   */
  private fileName;

  /**
   * Responsável por realizar a compressão do arquivo ou diretório desejado.
   * 
   * @param  \SplFileInfo $file Arquivo ou diretório ao qual se deseja comprimir.
   * @throws \Exception         Caso o diretório ou arquivo não exista.
   * @return String             Retornar o nome do arquivo .zip criado
   */
  public function compress(SplFileInfo $file)
  {
    // Implementação do método para compressão...
  }
}

Foram utilizadas as tags recomendadas pela PSR e uma organização deixando cada bloco de informação legível e limpo para consulta. Essa abordagem é extremamente importante pois, imagine em projetos de grande porte como por exemplo o Zend Framework ou Symfony,  caso um do frameworks mencionados não dispor de um bom PHPDoc, isso implicará em uma maior dificuldade de compreensão dos seus recursos.

As três tags descritas como recomendadas foram inclusas na classe e são ‘herdadas” pelos métodos e atributos, porém a PSR deixa aberto para que possa ser inserido de forma individual, particularmente não aprecio, pois aumenta  a carda de informações duplicadas.

Quais os benefícios de incluir um bom PHPDoc?

Podemos utilizar o recurso de autocomplete das IDE’s.

Deixar mais claro a que se propõe o recurso em questão.

Podemos utilizar ferramentas como Sami (Gerando documentação do seu sistema utilizando a API SAMI), para gerar uma documentação do sistema de forma automática, simples e eficaz.

Quais tags dispõem a PSR-5?

Abaixo segue lista contendo todas as tags disponíveis seguido do seu nome, elemento e descrição.

Espero ter conseguido demonstrar a importância do uso do PHPDoc, como tudo na vida devemos ter parcimônia, ou seja, devemos utilizar conforme necessário para enriquecer nosso código. Não tenha vergonha em consultar a documentação para ver qual tag melhor se enquadra para a situação em questão.

Caso tenham alguma dúvida, sugestão ou crítica convido a deixarem nos comentários, para que assim possamos aprender cada vez mais.

Até a próxima pessoal! 🙂