PHPDoc, um caminho para documentar código PHP

Já conteceu de esquecer o código que você mesmo escreveu?

É nesses momentos que o PHPDoc, um padrão de formatação de comentários da linguagem, pode ajudar a relembrar a lógica do código.

Não se trata de um simples comentário, mas sim de uma forma estruturada de comunicar ao utilizador como o código funciona. Seja dentro de uma classe ou quando ela for instanciada, o PHPDoc permite adicionar informações detalhadas sobre estruturas de código, como classes, métodos, propriedades, tipos, parâmetros e retornos, além de descrever o fluxo da lógica.

Para isso, as IDEs desempenham um papel importante, exibindo as informações documentadas por meio de janelas de diálogo e facilitando o uso com recursos como autocomplete.

Um simples exemplo de documentação com PHPDoc:

Como aparece no momento da instanciação:

Usando o VScode, colocamos o mouse sobre o método e temos todas as informações que foram definidas no pelo PHPDoc.

Esse é um simples exemplo, é possível gerar documentação dinâmica e completa a partir do PHPDoc utilizando ferramentas como o #phpDocumentor ou #ApiGen, mas esse é assunto para outro post.