PHPDocumentor

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.

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;
}
?>