PHPDOC
PHPDoc es una adaptación de javadoc para php que define un estándar oficial para comentar código php.
Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor
¿Qué conviene documentar dentro del código?. Fundamentalmente tres cosas:
| Tipo de documentación | Información | A quién va dirigida |
| La interfaz | Qué hace (no como lo hace) una función o un método de una clase. Qué parámetros hay que pasar. Qué devuelve. Ejemplo de uso. | Esta información es útil para las personas que utilizan funciones o clases diseñadas por otros |
| La implementación | Dentro de una función, cómo se lleva a cabo cada paso. Por qué se utiliza esta variable y no aquella. Qué algoritmo se utiliza. Qué hacen los métodos privados de una clase. | Esta información sólo interesa a las personas que necesiten depurar o actualizar el bloque de código. |
| La toma de decisiones | Por qué se ha implementado de una determinada forma y no de otra (p.e. por razones de rendimiento o por optimización de recursos, etc..). | Esta información interesa tanto a nivel de implementación (desarrollador) como a nivel funcional (responsable de desarrollo). |
Normalmente la información sobre la implementación no necesita salir del código.
Por el contrario, la información de la interfaz conviene pasarla a un documento independiente del código fuente (manual de uso). La persona que necesite utilizar una determinada librería de clases o funciones tendrá toda la información necesaria: qué hace cada elemento y cómo se utiliza. No necesita acceder al código fuente.
El problema con este tipo de documentación es que cada vez que se modifica algo en el código (actualizaciones, corrección de errores, etc...) hay que reflejarlo también en el manual de uso... doble trabajo.
Lo ideal por tanto sería poder automatizar de alguna forma este proceso.
Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor (www.phpdoc.org).
El funcionamiento básico se representa en el siguiente esquema:
Informacion tomada de: http://www.epsilon-eridani.com/cubic/ap/cubic.php/doc/phpDocumentor---documentacion-para-codigo-PHP-246.html
No hay comentarios:
Publicar un comentario