PHPDocumentor¶

phpDocumentor es un generador de documentación de código abierto escrito en PHP. Automáticamente analiza el código fuente PHP y produce la API de lectura y documentación del código fuente en una variedad de formatos. phpDocumentor genera la documentacion en base al estándar formal PHPDoc. Es compatible con la documentación del código orientado a objetos y programación procedural, además es capaz de crear documentos HTML, PDF, CHM y formatos Docbook. Se puede utilizar desde la línea de comandos o mediante una interfaz web. Tiene soporte para la vinculación entre la documentación, la incorporación de documentos a nivel de usuario como tutoriales, y la creación de código fuente resaltado con referencias cruzadas a la documentación en general de PHP. phpDocumentor es capaz de analizar toda la sintaxis de PHP y apoya PHP4 y PHP5. Se trata de un proyecto de código abierto y se distribuye bajo la licencia LGPL.

Ejemplo

/**
* Descripción breve (una línea)
*
* Descripción extensa. Todas las líneas que
* sean necesarias
* Todas las líneas comienzan con *
*
* Este DocBlock documenta la función suma()
*/
function suma()
{
...
}

En los DocBlock, unas de las muchas marcas que se pueden añadir son:¶

• @access: Si @access es ‘private’ no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados).

• @author: Autor del código.

• @copyright: Información sobre derechos.

• @deprecated: Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible.

• @example: Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted).

• @ignore: Evita que phpDocumentor documente un determinado elemento.

• @internal: Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores.

• @link: Para incluir un enlace (http://…) a un determinado recurso.

• @see: Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento).

• @since: Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución.

• @version: Versión actual del elemento

Marcas para funciones:¶

• @global: Permite especificar el uso de variables globales dentro de la función.

• @param: Parámetros que recibe la función. Formato:

  @param tipo $nombre_var comentario

• @return: Valor devuelto por la función. Formato:

  @return tipo comentario

Marca para variables:¶

• @var: Documenta los atributos de la clase. Formato:

  @var tipo comentario

Tipos de datos:¶

• array

• string

• boolean

• integer

• float

• object

• mixe

Ejemplo:

/**
* Dirección de correo
* @var string
* @access protected
*/
protected $_email;

/**
* Verifica si una direccion de correo es correcta o no.
*
* @return boolean true si la direccion es correcta
* @param string $email direccion de correo
*/
function checkEmailAddress ($email)
{
....
}

Bibliografía¶

Link de referencia Pagina oficial de PhpDocumentor