¿Cómo documenta sus funciones y clases de PHP en línea?

Sé que hay muchos estándares diferentes para la documentación en línea del código PHP. Esto es lo que quiero decir con la documentación en línea, y por favor corrígeme si hay un término mejor:

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

¿Cuál es la mejor y más ampliamente aceptada forma de documentación en línea? ¿Hay alguna herramienta para autogenerar tal documentación, o tiene que hacerse a mano?

No estoy interesado en generar manuales: quiero saber cómo generar el tipo de código que comenta más arriba, o “documentación en línea”.

PHPDoc , al igual que lo que ha publicado, es una forma ampliamente aceptada de documentación de PHP.

Puede usar Doxygen para generar automáticamente los documentos.

Editar: en términos de generar documentación en línea en su código, nunca encontré una herramienta que retroceda y lo haga de forma externa para un proyecto. Generalmente se deja en el ámbito del IDE para generar una plantilla mientras codifica.

Eclipse realmente hace un trabajo decente (es una de las pocas cosas que me gusta de Eclipse) y creo que Netbeans también lo hace. Cualquier IDE principal probablemente tendrá funcionalidad para ayudar con este tipo de generación de plantillas.

Escoge de:

  • Doxygen
  • phpDocumentator
  • Sami
  • ApiGen
  • Documentos API de CakePHP
  • phpDox

Consulte también el artículo de Wikipedia, “Comparación de generadores de documentación”, sección “por idioma” .

Por lo general, escribes los comentarios de docblock, aunque supongo que algunos IDE pueden crear una plantilla para ti.

De hecho, escribí un progtwig, que puede rastrear un progtwig en ejecución y detectar tipos de parámetros y escribirlos de nuevo como comentarios docblock . Es un poco problemático, pero funciona.

Creé un documentador muy simple de usar y compatible con phpdoc:

Ejemplo:

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

Ver en Github:

https://github.com/olaferlandsen/QuickDocumenter

¡Adiós!

Aunque no lo he utilizado por completo, Doxygen parece prometedor para esta tarea.

Si está familiarizado con la herramienta JavaDoc para Java, es bastante similar a eso. Utiliza el estilo Doxygen y luego ejecuta la herramienta sobre los archivos fuente para generar documentación.

No estoy seguro de lo que codifica pero tengo varios fragmentos (uso Textmate) que acabo de agregar mientras trabajo). He encontrado que esto termina con los mejores resultados ya que estoy completando los detalles en lugar de confiar en un sistema para hacerlo por mí.

Es más trabajo al principio pero parece valer la pena a largo plazo