Documentando PHP con phpDocumentor (2)

DocBlock

En phpDocumentor la documentación se distribuye en bloques DocBlock. Estos bloques siempre se colocan justo antes del elemento al que documentan y su formato es:

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

Los elementos que pueden ser documentados son:

define
function
class
class vars
include/require/include_once/require_once
global variables

Además se puede incluir documentación globlal a nivel de fichero y clase mediante la marca @package

Marcas (tags)

Dentro de un bloque DocBlock se pueden incluir marcas que serán interpretadas por phpDocumentor de forma especial.

Hay una serie de marcas estándar que pueden ir dentro de todos los DocBlock:

Marca	Significado
@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 inline {@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 inline {@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

Usuarios que han visto este tema también han visto...

- Expresiones regulares en PHP
- Resultados de una consulta a la BD en dos columnas
- El lenguaje SQL y PHP
- Crear un sistema de noticias con PHP
- Cómo comprimir a GZ un archivo con PHP

- Versión imprimible de este documento

- Enviar por e-mail este documento