PHPDocumentor

Enviado por Yukare em quinta-feira, 3 de Agosto de 2017 - 20:27

O que é o phpDocumentor? O que ele pode fazer?

Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.

phpDocumentor é uma ferramenta escrita em php desenvolvido para criar uma documentação completa direto do código fonte php e de documentação externa. A verdade é, o código php é tão claro que ele praticamente serve como sua própria documentação. phpDocumentor interpreta todos os tipos de estruturas lógicas já encontradas no PHP como arquivos, classes, funções, definições de constantes, variáveis globais, e funções/métodos de classe e os organiza em um formato de manual tradicional. Em adição, a partir da versão 1.3.0, elementos do código fonte introduzidos no php 5(constantes de classe, interfaces e outros) também podem ser interpretados, se o phpDocumentor for executado no PHP 5. A saída pode ser criada em vários formatos, como para visualização pela internet, impressão e integração com sistema IDE através de conversores para HTML, PDF, e CHM (arquivos de ajuda windows).

phpDocumentor gera documentação no formato de manual lendo comentários especiais chamados DocBlocks. DocBlocks são aonde você como autor do projeto de software deve documentar informações que sejam uteis que possam ser usadas pelos outros(ou você mesmo no futuro) para determinar como usar e estender o seu pacote PHP.

Mesmo que a habilidade de adicionar documentação sucinta no código fonte seja essencial, ela não substitui a importância de documentação mais detalhada que não esteja no código fonte, como um manual ou um tutorial tipo esse que você esta lendo agora. Se um texto como esse fosse colocado no phpDocumentor, ele serviria de pouca utilidade, além de estufar o código, porque seria difícil de localizar. Entretanto, a habilidade de criar ligações entre a documentação externa e a documentação no código fonte é essencial. A documentação externa para uma função deve ser capaz de referenciar a documentação dela no código fonte, e vice-versa, e com o phpDocumentor isto é finalmente possível.