Geração Automática de Documentação PHP?

Para o ActionScript 2, usei o NaturalDocs . No entanto, tem um suporte bastante fraco para o PHP. Eu olhei até agora no Doxygen e no phpDocumentor , mas sua produção é bastante feia na minha opinião. Alguém tem alguma experiência com a geração automática de documentação para o PHP? Eu preferiria usar tags de estilo javadoc, elas são fáceis de escrever e fáceis de lembrar.

ApiGen

http://apigen.org/

O ApiGen tem suporte para namespaces, pacotes, links entre documentação, referência cruzada para classs padrão do PHP e documentação geral, criação de código-fonte destacado e suporte experimental para características do PHP 5.4.

DocBlox

http://www.docblox-project.org/

API compatível com PHP 5.3 Gerador de documentação voltado para projetos de todos os tamanhos e continuous integration.

capaz de analisar e transformar completamente o Zend Framework 2

Existem duas ferramentas bem conhecidas e muitas vezes usadas que podem gerar documentos API a partir de docblocks:

  • phpDocumentor , que é específico para o PHP, e provavelmente é uma das ferramentas mais utilizadas para projetos PHP.
  • e Doxygen , que é mais para C, mas é usado para PHP por algumas pessoas.

Sobre as “diretrizes”: eu diria que depende de seus projetos, mas, pelo menos, eu esperaria ver:

  • uma descrição do que o método / function faz
  • parâmetros, com @param type name description of the parameter
  • valor de retorno, com a @return type description of the return value
  • exceções, com @throws type description of the exception that can be thrown

Uma ótima coisa é que o IDE recente (como Eclipse PDT , por exemplo) , pode ler e interpretar esses marcadores, para fornecer sugestões quando você codifica 😉

Além disso, existem mais e mais ferramentas PHP que usam php docblocks para algum outro propósito que a documentação.

Por exemplo, o PHPUnit permite que você especifique algumas coisas relacionadas ao teste usando algumas tags específicas – veja Anotações .

O PHPDoc é provavelmente tão bom como você conseguirá isso em termos de comentários em linha do estilo Javadoc. Você também pode querer olhar para o PHPXRef .

Sim, phpDocumentor ( http://www.phpdoc.org/ ) é uma ferramenta padrão aceitável para autodocs PHP. É o padrão de fato.

É aceitável seguir as diretrizes gerais do JavaDoc para o código ao documentar o código PHP. No entanto, você vai encontrar casos em que isso não é suficiente porque PHP e Java são diferentes idiomas.

Por exemplo, as funções PHP não têm nenhum tipo de retorno e é inevitável (e às vezes desejável) para uma function retornar um tipo com um contexto e outro tipo com um segundo contexto. As diretrizes do JavaDoc não vão ajudar com isso, porque é impossível fazer em Java.

Confira o PHPDoctor http://peej.github.com/phpdoctor/ , um clipe Javadoc com características simples e completas para PHP.

phpDocumentor pode produzir em um estilo semelhante à documentação php.net (e é incorporado com layouts inteligentes e não sábios)

A base de código do WordPress é documentada usando tags phpdoc (veja isso ) e geralmente é bastante bom – é processado aqui usando o phpDocumentor .

A maior parte do código que eu escrevo é substancial o suficiente para que eu precise pensar sobre os documentos de autogeneração para é feito em .Net, então eu não posso dar grande parte da perspectiva de um escritor de documentação.

Se um problema é feio, eu simplesmente mudaria a folha de estilo para uma opção personalizada. Se você não quer replace o gerado, você pode usar um plugin do Firefox como Stylish .

Você pode editar o arquivo de modelo para adicionar sua própria folha de estilo para replace a existente.

Intereting Posts