plantilla - phpdocumentor tutorial
Generación automática de documentación PHP? (9)
Para ActionScript 2, he usado NaturalDocs . Sin embargo, tiene un soporte bastante pobre para PHP. Miré hasta ahora a Doxygen y phpDocumentor , pero su salida es bastante fea en mi opinión. ¿Alguien tiene alguna experiencia con la generación automática de documentación para PHP? Preferiría poder usar etiquetas de estilo javadoc, son cortas para escribir y fáciles de recordar.
Puede editar el archivo de la plantilla para agregar su propia hoja de estilo y anular la existente.
Si feo es un problema, simplemente cambiaría la hoja de estilo por una personalizada. Si no desea sobrescribir el generado, puede usar un complemento de Firefox como Stylish .
phpDocumentor puede generar resultados en un estilo similar a la documentación de php.net (y está integrado con diseños inteligentes y no inteligentes)
Hay dos herramientas conocidas y de uso frecuente que pueden generar documentos API desde docblocks:
- phpDocumentor , que es específico de PHP, y es probablemente una de las herramientas más utilizadas para proyectos de PHP
- y Doxygen , que es más para C, pero algunas personas lo usan para PHP.
Acerca de las "pautas": Yo diría que depende de sus proyectos, pero, al menos, esperaría ver:
- una descripción de lo que hace el método / función
- parámetros, con
@param type name description of the parameter - valor de retorno, con
@return type description of the return value - excepciones, con
@throws type description of the exception that can be thrown
Una gran cosa es que IDE reciente (como Eclipse PDT , por ejemplo) , puede leer e interpretar esos marcadores, para proporcionar pistas cuando estás codificando ;-)
Además, cada vez hay más herramientas PHP que utilizan docblocks de php para otro fin que no sea la documentación.
Por ejemplo, PHPUnit te permite especificar algunas cosas relacionadas con las pruebas usando algunas etiquetas específicas - ver Anotaciones .
La base de código de Wordpress está documentada usando etiquetas phpdoc (ver esto ) y generalmente es bastante buena, se representa aquí usando phpDocumentor .
La mayor parte del código que escribo que es lo suficientemente sustancial como para pensar en la autogeneración de documentos se hace en .Net, por lo que no puedo dar mucha perspectiva a un escritor de documentación.
PHPDoc es probablemente tan bueno como lo obtendrás en términos de comentarios en línea estilo Javadoc. También es posible que desee ver PHPXRef .
Sí, phpDocumentor ( http://www.phpdoc.org/ ) es una herramienta estándar aceptable para autodocs de PHP. Es el estándar de facto.
Es aceptable seguir las pautas generales de JavaDoc para el código al documentar el código PHP. Sin embargo, te encontrarás con casos en los que eso no es suficiente porque PHP y Java son idiomas diferentes.
Por ejemplo, las funciones de PHP no tienen un tipo de devolución y es inevitable (y en ocasiones deseable) que una función devuelva un tipo con un contexto y otro tipo con un segundo contexto. Las pautas de JavaDoc no van a ayudar con eso, porque es imposible hacerlo en Java.
Visite PHPDoctor http://peej.github.com/phpdoctor/ , un clon de Javadoc simple pero completo para PHP.
ApiGen
ApiGen tiene soporte para espacios de nombres PHP 5.3, paquetes, enlaces entre documentación, referencias cruzadas a clases estándar de PHP y documentación general, creación de código fuente resaltado y soporte experimental para rasgos PHP 5.4.
DocBlox
http://www.docblox-project.org/
PHP 5.3 generador de documentación API compatible dirigido a proyectos de todos los tamaños e integración continua.
capaz de analizar completamente y transformar Zend Framework 2