Documentação de código: Doxygen + PHP

22 02 2007

Sempre que precisei gerar documentação técnica de alguma aplicação utilizei phpDocumentor. Afinal, é o mais conhecido, muitos projetos utilizam e não conhecia nenhuma outra opção viável. Além disso, estava acostumado com javadoc (pois é, durante tempos trabalhei com java).

phpDocumentor é um auto-proclamado padrão para a documentação de softwares desenvolvidos em PHP. É bastante semelhante (por ser um “clone”) ao javadoc e pode ser utilizado tanto em linha de comando quanto em uma interface web:

phpdoc web interface

A instalação também é bastante simples:

$pear download phpdocumentor

Após baixar, basta descompactar o arquivo e acessar, via localhost mesmo, que a interface acima será exibida.

Algumas das principais features encontradas nele, segundo os desenvolvedores, são:

  • Geração de documentação em HTML, PDF, CHM (windows help) e XML DocBook
  • Muito rápido (particularmente, não concordo com isso)
  • Interface via web e linha de comando
  • Documentação totalmente customizável utilizando templates “smarty-based”
  • Linkagem automática de heranças entre classes
  • Geração de TODO list utilizando tags @todo no código

Realmente, phpDocumentor é muito bom. Mas não é a única forma de se criar documentação.

DOXYGEN

DoxygeN, assim como phpDocumentor, é utilizado para geração de documentação com base em código fonte. Além de PHP (que tem suporte desde a versão 1.2.17), Doxygem pode ser utilizado para criar documentação de aplicações escritas em C, C++, C#, Objective C, Java, Python, IDL e D.
Os formatos de documentação gerados são HTML, LATEX, RTF, PS (postscript), PDF, XML, CHM e man pages unix.

As tags escritas para serem utilizadas pelo phpDocumentor (boa parte) também são utilizadas pelo doxygen, o que ajuda a deixar a documentação mais completa.

A instalação, dependendo o sistema que se está utilizando, pode não ser tão simples, mas também não possui nenhum segredo: basta baixar um pacote pronto para o sistema e instalar ou, em último caso, baixar os fontes e compilar.

Entre os diversos features encontrados no doxygen, alguns podem ser destacados:

  • Geração de documentação em diversos formatos, como citado acima
  • Não é indispensável documentar o código explicitamente
  • Suporta documentação de arquivos, namespaces (mesmo PHP sem ter – ainda – namespaces, a documentação gerada contém também documentação de namespaces), pacotes, classes, estruturas, templates, funções, typedefs, enums, defines e variáveis (algumas coisas não disponíveis em PHP)
  • Compatível com documentação no padrão JavaDoc, Qt-Doc e ECMA-334 (não imagino como é, mas é a especificação do C#)
  • Geração de diagramas de classe e de colaboração em HTML, com mapas de imagens (imagens em postscripts também)

diagrama de classe

  • Flexivel com o posicionamento de comentários
  • Sistema de busca interna, baseado em rank, para procurar por strings na documentação de classe ou de membros (uau! o seu próprio google na documentação)
  • Tags HTML colocadas na documentação são transformadas automáticamente em suas equivalentes na geração da documentação em outros formatos

Para geração de documentação pode se utilizar um arquivo de configuração, onde todos os parâmetros utilizados pelo doxygen serão lidos e processados. O arquivo de configuração pode ser escrito tanto manualmente, com ajuda do manual, quanto por ferramentas externas, como por exemplo, este excelente plugin para o eclipse.

Um exemplo de arquivo de configuração que utilizo pode ser encontrado aqui. Está totalmente comentado.

Futuramente um pequeno passo a passo para a instalação do eclipse+doxygen+plugins do eclipse será coberto aqui.

Fica ai então, a dica para documentação de um próximo projeto.

Anúncios

Ações

Information

2 responses

22 11 2007
Adalberto Joco

Excelente !

Ia só comentar, mas em paralelo abri em outra aba o link para seu arquivo de config do Doxygen (404).

################

Qual ferramenta vc prefere para gerar documentação ?

3 08 2009
demoncyber

Olá

Você conseguiu usar o php com classes e orientação a objetos com o doxygen sem problemas ???

Se sim teria como me enviar um exemplo =/ estou tendo dificuldades com isto.

( estou usando o 1.5.7 )

Att.

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s




%d blogueiros gostam disto: