PHPDocumentor
- Área: Especificaciones de Codificación y Construcción
- Carácter del recurso: Recomendado
- Tecnologías: PHP
Descripción
Es un generador de documentación de código en lenguaje PHP.
Elementos a documentar
Los elementos susceptibles de ser documentados obedecen a la siguiente lista:
- Sentencias define[_once].
- Sentencias include[_once].
- Funciones.
- Clases.
- Métodos y atributos.
- Variables globales.
Existe una estructura adicional documentable llamada "archivo de código". Un bloque de documentación hace referencia al archivo y no a un elemento específico si se cumple alguna de las siguientes condiciones.
- Si el primer bloque de documentación en el archivo de código incluye la etiqueta @package y no se encuentra sucedido por un elemento class.
- Si el primer bloque de documentación en el archivo de código antecede a otro bloque documentación.
Etiquetas para documentar
Las etiquetas proporcionan información adicional acerca de la entidad documentada. Las etiquetas constan de una palabra que las identifica precedida por el símbolo de arroba ('@'). Cada una de las etiquetas tiene su propia lista de parámetros que se referencia a continuación.
Tabla de etiquetas | Tipo |
---|---|
@abstract | Especifica que una clase, un método o una variable son abstractos. |
@access public|private|protected | Controla la aparición de un elemento en la documentación generada. Si se declara como private, el elemento no aparece a no ser que se genere la documentación de forma específica. |
@author | Autor del elemento con la posibilidad de incluir un elemento dentro de <>. |
@category nombre | Especifica la categoría a la cual pertenece la entidad documentada dentro del paquete. |
@deprecated | Indica que el elemento esta discontinuado. Determina que el elemento es obsoleto y no debería utilizarse ya que puede ser retirado en el futuro cercano. |
@example | Se utiliza para incluir una ejemplo. |
@final | Determina que el elemento es final y por lo tanto no puede ser sobrescrito o crear subclases de él. |
@ignore | Se ignora al elemento. |
@internal información_no_publicable | Especifica información que no se incluye en la documentación pública. |
@link URL [texto] | Despliega un hiperenlace en la documentación. |
@see | Enlaza con la documentación de otro elemento. |
@package nombre | Especifica el paquete que agrupa de manera documental las clases y funciones especificadas. |
@param tipo1|tipo2|... $nombre_de_variable descripción | Indica el tipo y el nombre del parámetro. |
@static | La variable o la función es estática. |
@since información de versión | Documenta cuando/en que versión se agregó el elemento. |
@return tipo_de_datos | Describe el tipo de retorno de un método o función. |
@todo informacion | Documenta cambios que serán realizados en el futuro. |
@throws información_de_excepciones | Especifica las posibles excepciones lanzadas por la función o método actual. |
@version | Versión del elemento. |
Uso de plantillas para documentar bloques
Se muestra a continuación ejemplos para documentar bloques, con y sin plantillas:
// Ejemplo sin plantillas
<?php
class WisdomDispenser
{
/**
* @access protected
* @var string
*/
private $firstSaying = 'Obey the golden rule.';
/**
* @access protected
* @var string
*/
private $secondSaying = 'Get in or get out.';
/**
* @access protected
* @var string
* @author Albert Einstein <masterof@relativity.org>
*/
private $thirdSaying = 'Everything is relative';
}
?>
// Ejemplo con plantillas
<?php
class WisdomDispenser
{
/**#@+
* @access protected
* @var string
*/
private $firstSaying = 'Obey the golden rule.';
private $secondSaying = 'Get in or get out.';
/**
* @author Albert Einstein <masterof@relativity.org>
*/
private $thirdSaying = 'Everything is relative';
/**#@-*/
}
?>
Como documentar un bloque
El proceso de documentación comienza con el elemento más básico de phpDocumentor: un bloque de documentación o DocBlock. Un DocBlock contiene tres segmentos básicos en este orden:
- La Descripción corta
- La Descripción larga
- Las etiquetas
<php
public function isLoggedIn();
/**
* Devuelve la información del usuario sobre la cuenta
*
* This method is used to retrieve the account corresponding
* to a given login. <b>Note:</b> it is not required that
* the user be currently logged in.
*
* @access public
* @param string $user user name of the account
* @return Account
*/
public function getAccount($user = '');
}
?>
Ejemplos de uso
<?php
/**
* Ejemplo, phpDocumentor Quickstart
*
* Este archivo muestra el uso de la etiqueta @name
* @author MADEJA
* @version 1.0
* @package sample
*/
/**
* declaración de la variable global DocBlock
* @global integer $GLOBALS['_myvar']
*/
$GLOBALS['_myvar'] = 6;
/**
* Observe que la etiqueta @name tag no valida lo que se le introduce
* @global string $GLOBALS['turkey']
* @name $turkify
*/
$GLOBALS['turkey'] = 'tester';
/**
* Ejemplo simple de uso de la función @global
*
* Observe que la variable $turkey no está enlazada en la documentación
* {@link $turkify} porque se ha realizado un mal ejemplo de uso de la etiqueta @name
* @global integer
* @global string Representa a la descripción opcional
*/
function testit()
{
global $_myvar, $turkey;
}
?>
Ventajas e inconvenientes
- La documentación generada podrá incluir tutoriales o manuales, para lo que se utilizará la sintaxis de DocBook. Los tutoriales, en pocas palabras, se incorporan al proyecto en su propio directorio, y son utilizados por PhpDocumentor para obtener de ellos la información que contienen y situarla dentro de la documentación de nuestro proyecto
- Salida en varios formatos (HTML, PDF, CHM, XML etc.)
- Crea documentación en función de los diferentes grupos de usuarios a partir de la anotación @private
- Permite la ejecución por línea de comandos y por interfaz web
- Documentación extensa disponible
Requisitos e incompatibilidades
- PHP versión 4.1.0 o mayor
- Hace uso de Pear para su instalación o puede directamente instalarse en el servidor web
Interacciones
DocBook es un complemento que puede interaccionar con PHPDocumentor aumentando las posibilidades de éste. Se trata de un esquema que se adapta particularmente bien a libros y artículos acerca de hardware y software (aunque no se limita a este tipo de aplicaciones).
Existe otra alternativa a PHPDocumentor llamada Doxygen complementada con PHPxRef.
Enlaces externos
Contenidos relacionados
Código | Título | Tipo | Carácter | |
---|---|---|---|---|
LIBP-0102 | Reglas de construcción en PHP | Libro de pautas | Directriz | Obligatoria |
LIBP-0089 | Convenio de codificación específico para PHP | Libro de pautas | Directriz | Obligatoria |
Código | Título | Tipo | Carácter |
---|---|---|---|
RECU-0110 | Doxygen | Referencia | Permitido |