Documentar en PHP

Al comenzar a documentar una de las primeras cuestiones a resolver es el público de la misma. Al escribir documentación sobre un proyecto de fuente abierta se debe pensar que el alcance de la documentación es muy elevado. Por un lado estarán los usuarios finales y por otro lado programadores que quieran continuar el desarrollo o incluso reparar defectos en el mismo. Estos dos públicos tienen diferentes necesidades .

Un usuario final generalmente quiere:

• El estilo de las instrucciones escritas, eso explica y describe los conceptos generales más allá de cómo una variable particular se usa
• La información de la interfaz , ningún detalle de bajo nivel
• Los ejemplos de cómo usar, y guías didácticas

Considerando que un programador además puede querer:

• Los detalles del programa en especial las relaciones entre los diferentes elementos, qué elementos usan otros, etc
• Donde ocurre una acción o serie de acciones en el código fuente
• Cómo extender el código para agregar una nueva funcionalidad

En PHP es posible definir dos niveles de documentación que se mantienen en directorios separados con el uso de PHPDocumentator. Por ejemplo, si utilizamos la etiqueta @access a private,se generan los elementos como documentación para el programador, esto elementos se ignoraran en la generación de documentación publica. Es recomendable mantener estos niveles separados.

El comentario que documenta una estructura se debe ubicar justo antes de la declaración de dicha entidad. Los elementos susceptibles de ser documentados y que Madeja recomienda documentar, obedecen a la siguiente lista.

• Sentencias define[_once].
• Sentencias include[_once].
• Funciones.
• Clases.
• Métodos y atributos.
• Variables globales.

Existe una estructura adicional que puede ser documentada y es el 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.

El proceso de la documentación empieza 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 = '');
}
?>

Cuando vamos a documentar varios elementos similares es recomendable el uso de una plantilla. Una plantilla se define de la misma manera que un bloque normal, lo único que cambia es el encabezado de la primera línea /*#@+ en lugar de /* , la declaración se irá añadiendo a los elementos hasta encontrar un elemento de cierre delimitado con /*#@-/. Se recomienda el uso de plantillas para favorecer la legibilidad del código

// 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';
  /**#@-*/
}
?>

Las etiquetas son opcionales y 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.