phpDocumentor es un instrumento de documentación que nos permite crear fácilmente la documentación del código fuente PHP. La documentación se extrae del código fuente y de los comentarios especiales dentro del mismo; estos comentarios son muy similares a los utilizados por JavaDoc.
Este ejemplo demuestra cómo podríamos documentar una función muy sencilla:
* Suma dos enteros juntos
*
* @param int $valor1 Valor base
* @param int $valor2 Valor para agregar
* @return int Valor resultante
* /
function sumar($valor1, $valor2)
(
return ((int)$valor1 + (int)$valor2)
)
El comentario de varias líneas denota un "DocBlock", observe que se utiliza un doble asterisco en la salida. La primera línea es una descripción general de la función, esta descripción puede abarcar más de una línea. @param y @return son las etiquetas.
La etiqueta @param se utiliza para definir un parámetro en el formato (el nombre es opcional):
@param type [$nombre] Descripción
La etiqueta @return se utiliza para definir el valor de retorno en el formato:
@return type Descripción
Así pues, nuestro ejemplo inicial nos está diciendo que la función suma() tiene dos parámetros enteros que se sumarán y devolverá el valor entero resultante.
Cuando necesitamos documentar funciones complejas, podemos proveer dos descripciones una descripción larga y una descripción corta. Este ejemplo demuestra la forma en que podemos hacer esto:
/ **
* Proceso complejo
*
* Descripción detallada de la función que abarca más de
* una línea
*
* @param int $valor1 Valor base
* @param int $valor2 Valor para agregar
* @return int Valor resultante
* /
function algunaFuncionCompleja($valor1, $valor2)
(
/ / Hace un procesamiento complejo
)
Las funciones no son los únicos elementos que pueden ser documentadas. Los elementos que podemos documentar incluyen:
- métodos de clase
- clase variables
- clases
- define()
- archivos
- declaraciones de funciones
- variables globales (requiere el uso de la etiqueta @global)
- include() / include_once ()
- require() / require_once ()
Esta lista define algunas etiquetas comunes que es probable que encuentre:
- @access private|protected|public|
- @author nombre
- @param type [$nombre] Descripción
- @return type Descripción
- @static
El "Docblocks" es facil de leer cuando se muestra en el código, pero, más importante aún, puede generar automáticamente la documentación del código fuente.
Para obtener más información sobre el uso phpDocumentor por favor vaya a http://www.phpdoc.org/.