Escrevendo documentação para projetos PHP: do A ao Z

Introdução

A documentação não é apenas um complemento agradável para o projeto, mas um elemento criticamente importante do desenvolvimento profissional em PHP. Uma documentação bem escrita acelera a integração de novos desenvolvedores, reduz o número de erros e torna o código sustentável mesmo após anos. Neste artigo, percorreremos o caminho desde os fundamentos da escrita de comentários até a criação de documentação técnica completa para seu projeto PHP.

Abordaremos os padrões PHPDoc, melhores práticas de formatação, ferramentas de geração automática e responderemos à pergunta: como tornar a documentação útil, e não apenas formal.

Fundamentos do PHPDoc: como comentar código PHP corretamente

O padrão PHPDoc (ou DocBlock) é a forma amplamente aceita de documentar código PHP. Ele é baseado em comentários especiais que começam com /** e terminam com */. Cada bloco descreve um elemento do código: classe, método, propriedade ou função.

Estrutura básica do DocBlock

Um bloco de documentação mínimo inclui uma descrição e um conjunto de tags (anotações). Vejamos um exemplo para um método simples:

<?php\n\n/**\n * Calcula a soma de dois números.\n *\n * @param int $a Primeira parcela.\n * @param int $b Segunda parcela.\n * @return int Soma dos números.\n */\nfunction sum(int $a, int $b): int {\n    return $a + $b;\n}\n?>

Tags principais do PHPDoc

\n
• @param — descreve um parâmetro de método ou função. Formato: @param tipo $nome Descrição.
\n
• @return — indica o tipo de retorno e sua descrição.
\n
• @var — usado para propriedades de classe, para indicar seu tipo.
\n
• @throws — documenta exceções que o método pode lançar.
\n
• @see — link para outro elemento da documentação ou recurso externo.
\n
• @deprecated — marca um elemento como obsoleto, indicando uma alternativa.
\n

Exemplo para uma classe com várias tags:

<?php\n\n/**\n * Classe para trabalhar com banco de dados.\n *\n * @package App\\Database\n * @author  João Silva\n * @version 1.0.0\n */\nclass Database {\n    /**\n     * @var PDO Conexão com o BD.\n     */\n    private PDO $connection;\n\n    /**\n     * Estabelece a conexão com o banco de dados.\n     *\n     * @param string $dsn  String de conexão DSN.\n     * @param string $user Nome de usuário.\n     * @param string $pass Senha.\n     *\n     * @throws PDOException Se não for possível conectar.\n     */\n    public function connect(string $dsn, string $user, string $pass): void {\n        $this->connection = new PDO($dsn, $user, $pass);\n    }\n}\n?>

Ferramentas para geração de documentação PHP

Manter a documentação manualmente em formato HTML não é eficiente. Os geradores automáticos vêm em socorro. O mais popular é o phpDocumentor (phpdoc).

Instalação e uso básico do phpDocumentor

Você pode instalar o phpDocumentor via Composer:

composer require --dev phpdocumentor/phpdocumentor

Após a instalação, execute a geração da documentação a partir da raiz do projeto:

vendor/bin/phpdoc -d src -t docs

Onde -d src é a pasta com o código-fonte e -t docs é a pasta onde a documentação HTML gerada será salva.

Outras ferramentas úteis

\n
• Doxygen — suporta não apenas PHP, mas também C++, Python, Java. Adequado para projetos em linguagens mistas.
\n
• Sami — um gerador de documentação moderno que pode criar várias versões da documentação para diferentes branches do código.
\n
• ApiGen — um gerador leve, focado na simplicidade de uso.
\n

Melhores práticas para escrever documentação PHP

Documentação de qualidade é