Como você documenta suas funções e classs PHP no inline?

Eu sei que existem muitos padrões diferentes para a documentação inline do código PHP. Veja o que eu quero dizer com documentação interna, e corrija-me se houver um termo melhor:

/** * This is the description for the class below. * * @package my-package * @subpackage my-subpackage * @author my-name * @version my-version * ... */ class orderActions { ... 

Qual é a melhor e mais aceita forma de documentação inline? Existem ferramentas para gerar automaticamente essa documentação, ou deve ser feito manualmente?

Não estou interessado em gerar manuais – Quero saber como gerar o tipo de código comentando acima, ou “documentação em linha”.

O PHPDoc , como o que publicou, é uma forma amplamente aceita de documentação do PHP.

Você pode usar Doxygen para gerar automaticamente os documentos.

Editar: Em termos de geração de documentação em linha em seu código, nunca encontrei uma ferramenta que volte e faça isso externamente para um projeto. Geralmente, é deixado no domínio do IDE gerar um modelo enquanto você codifica.

Eclipse realmente faz um trabalho digno disso (é uma das poucas coisas que eu gosto sobre o Eclipse) e acredito que o Netbeans também. Qualquer IDE importante provavelmente terá funcionalidades para ajudar com esse tipo de geração de modelo.

Escolha entre:

  • Doxygen
  • phpDocumentator
  • Sami
  • ApiGen
  • CakePHP API docs
  • phpDox

Veja também o artigo da Wikipédia, “Comparação de geradores de documentação”, seção “por Idioma” .

Normalmente, você escreveria os comentários do docblock para si mesmo, embora eu suponha que alguns IDEs podem criar um modelo para você.

Na verdade, escrevi um programa, que pode rastrear um programa em execução e detectar tipos de parâmetros e gravá-los como comentários do docblock . É um pouco buggy, mas é um tipo de trabalho.

Eu criei um documentador muito simples de usar e compatível com phpdoc:

Exemplo:

 parseString(" /** * Sanitize string * * @sinse 1.0 * @version 1.0 */ "); foreach( $docs->result() as $doc) { highlight_string( print_r( $doc , true ) ); echo "
"; } ?>

Veja em Github:

https://github.com/olaferlandsen/QuickDocumenter

Tchau!

Embora não o tenha utilizado completamente, o Doxygen parece promissor para esta tarefa.

Se você está familiarizado com a ferramenta JavaDoc para Java, é bastante semelhante a isso. Você usa o estilo Doxygen e depois executa a ferramenta em seus arquivos de origem para produzir documentação.

Não tenho certeza do que você codifica, mas eu tenho vários fragments (eu uso Textmate) que eu apenas adiciono enquanto estou trabalhando) Eu achei que isso acaba com os melhores resultados desde que estou preenchendo os detalhes em vez de confiar em um sistema para fazer isso por mim.

É mais trabalho no começo, mas parece valer a pena a longo prazo

Intereting Posts