Usando documentação externa

Enviado por Yukare em terça-feira, 8 de Agosto de 2017 - 16:04

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>