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.
Escrevendo documentação externa e criando links da documentação do código fonte.
Mesmo sendo a documentação interpretada direto do fonte muito útil, ela não pode suportar por sí só. Em adição, documentação verdadeiramente útil deve ser sucinta o suficiente, se não o código fonte é obscurecido pela documentação. Documentação externa é um dever para uma solução de documentação completa. Entretanto, a documentação externa deve ser ligações com a documentação da API para ser útil. Com as constantes mudanças da documentação da API, é muito fácil para a documentação externa se tornar desatualizada. Além disso, a documentação externa deve estar em um formato que possa ser convertido para outros formatos como HTML, PDF e XML.
phpDocumentor prove uma simples e elegante solução para este problema. Documentação externa do formato DocBook pode ser facilmente convertida para outros formatos. Usando tags inline, o phpDocumentor pode gerar um manual consistente em vários formatos combinando a saída da interpretação do código fonte com a documentação externa.
<refentry id="{@id}"> <refnamediv> <refname>Simple Tutorial</refname> <refpurpose>The simplest Tutorial Possible</refpurpose> </refnamediv> <refsynopsisdiv> <author> Gregory Beaver <authorblurb> </authorblurb> </author> </refsynopsisdiv> <refsect1 id="{@id intro}"> <para>Hello World</para> </refsect1> </refentry>