Según el sitio http://www.phpdoc.org/, phpDocumentor es la herramienta estándar para auto-documentación en PHP; es decir, se puede generar documentación de forma automática tomando como base el código fuente. Usualmente esta herramienta es comparada con lo que Javadoc hace en Java.
Algunas de las ventajas de usar phpDocumentor son la ayuda obvia que recibe el programador para que todas sus aplicaciones tengan un formato de documentación similar, que además, es el mismo formato de documentación de cientos de programadores PHP, si todos usáramos el mismo formato de documentación sería bastante más sencillo tomar un código fuente iniciado por otra persona; además, usando este tipo de herramientas el programador “se obliga” a ir llenando los campos necesarios para documentar y seguir una serie de “buenas prácticas” que posiblemente pasaría por alto si no contara con la herramienta. Finalmente, es muy sencillo pasar de comentarios en el código fuente a tener preparado un documento (por ejemplo en HTML) con todo el detalle de los archivos, clases, funciones, etc. que utiliza una aplicación, explicando los parámetros de entrada, los valores de retorno, etc.
Con phpDocumentor es fácil estandarizar por ejemplo la documentación sobre qué hace una función, qué parámetros recibe, que valores devuelve, cómo se lleva a cabo cada paso, por qué algo se programó de una forma y no de otra, etc.
Algunas de las funcionalidades de phpDocumentor es que logra exportar todos estos comentarios a formato PDF, HTML u otros; tiene interfaz web o por medio de línea de comandos, manejo automático para los README/CHANGELOG/INSTALL/FAQ, consulte el listado completo de características (en Inglés)
Puede leer más sobre phpDocumentor en el siguiente enlace:
