Geração automática de documentação PHP? [fechado]
Para o ActionScript 2, useiNaturalDocs . No entanto, tem um apoio muito pobre para o PHP. Eu olhei até agora para Doxygen e phpDocumentor , mas a sua produção é muito feia na minha opinião. Alguém tem alguma experiência com a geração automática de documentação para PHP? Eu prefiro ser capaz de usar tags estilo javadoc, eles são curtos para escrever e fácil de lembrar.
9 answers
ApiGen
O ApiGen tem suporte para espaços de nomes de PHP 5.3, pacotes, ligação entre documentação, referenciação cruzada para classes padrão de PHP e Documentação Geral, criação de código fonte realçado e suporte experimental para traços de PHP 5.4.
DocBlox
Http://www.docblox-project.org/
Gerador de documentação API compatível com o PHP 5.3, destinado a projectos de todas as dimensões e contínuos Integracao.
Capaz de processar e transformar completamente o Zend Framework 2
Existem duas ferramentas bem conhecidas e frequentemente usadas que podem gerar API doc a partir de docblocks:
- phpDocumentor , que é específico do PHP, e é provavelmente uma das ferramentas mais usadas para projectos 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 / função
- parâmetros, com
@param type name description of the parameter - valor de retorno, com
@return type description of the return value - excepções, com
@throws type description of the exception that can be thrown
Uma grande coisa é que o IDE recente (como Eclipse PDT , por exemplo) , pode ler e interpretar esses marcadores, para dar dicas quando estiver a codificar ; -)
Além disso, há mais e mais ferramentas de PHP que usam docblocks de php para algum outro propósito que a documentação.
Por exemplo, o PHPUnit permite-lhe especificar algumas coisas relacionadas com testes usando algumas etiquetas específicas -- ver [[39]}anotações .
PHPDoc é provavelmente tão bom quanto você vai obtê-lo em termos de estilo Javadoc comentando em linha. Você também pode querer olhar para PHPXRef .
SIM, phpDocumentor ( http://www.phpdoc.org/) é uma ferramenta padrão aceitável para os autodocs PHP. É o padrão de facto.
É aceitável seguir as orientações gerais 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 linguagens diferentes.
Por exemplo, as funções PHP não têm nenhum tipo de retorno e é inevitável (e às vezes desejável) que uma função retorne um tipo com um contexto, e outro tipo com um segundo contexto. As Diretrizes JavaDoc não vão ajudar com isso, porque é impossível fazer em Java.
Vê o PHPDoctor http://peej.github.com/phpdoctor/, Um clone Javadoc simples e completo para PHP.
O PhpDocumentor pode sair num estilo semelhante ao php.net documentação (e incorporada com layouts inteligentes e não inteligentes)
O código-base do Wordpress está documentado usando etiquetas phpdoc (ver este) e é geralmente muito bom-é renderizado aqui Usando phpDocumentor .
A maior parte do código que eu escrevo é suficientemente substancial para que eu precise pensar em autogenerar docs para é feito em. Net, então eu não posso dar grande parte da perspectiva de um escritor de documentação embora
Poderá editar o ficheiro de modelo para adicionar a sua própria 'stylesheet' para substituir a existente.