¿Por qué es importante generar documentación?
La programación es, generalmente, un entorno colaborativo, especialmente en proyectos de cierta emvergadura donde varios programadores y analístas trabajan de forma conjunta.
Cada programador tiene una forma concreta de comentar y de programar, y esto es un inconveniente porque dota de mucha hetereogeneidad a los proyectos haciendo que los programadores sepan dificilmente para qué son determinadas clases o funciones. Y más grave todavía es cuando hay que volver a retomar un proyecto hace tiempo olvidado.
Más motivos para utilizar una documentación sistemática es la tendencia actual del software de ser fabricarlo como si fueran piezas que fueran fácilmente interconectadas, por lo que una aplicación web por ejemplo, pudiera integrar fácilmente un foro o un blog. Generar una documentación estándar da muchas facilidades al entendimiento del código.
Además, generar una documentación que siga un cierto estándar nos va a permitir automatizar su generación en otros documentos como páginas HTML o PDFs además de poder integrarlo con los famosos entornos IDE de programación de forma que conforme escribimos veamos la descripción de la función, así como sus parámetros.
¿Qué es PHPDocumentor?
Es una herramienta que podemos instalar mediante PEAR con lo cual podemos generar automáticamente el código fuente. Para instalarla en nuestro servidor podemos hacerlo de la siguiente manera:
$ sudo apt-get install php-pear
Una vez instalado PEAR, instalamos phpDocumentor
$ pear channel-discover pear.phpdoc.org
$ pear install phpdoc/phpDocumentor-alpha
También es posible que tengamos que instalar las siguiente extensiones para poder generar gráficos para los diagramas de clases y para poder parsear el código fuente, aunque algunos servidores ya traen este software instalado.
$ sudo apt-get install php-xsl
$ sudo apt-get install graphviz
Su uso más básico podemos ejecutarlo desde la consola de comandos indicándole la carpeta donde está el código fuente y la carpeta de destino
$ phpdoc -d . -t docs
DocBlocks
La documentación de PHPDoc está basada en bloques de comentarios conocidos como DocBlocks.
En este ejemplo, vamos a ver como es la anatomía de uno de estos bloques
/**
* This is the short description for a DocBlock.
*
* This is the long description for a DocBlock.
*
* * Markdown style lists function too
* * Just try this out once
*
* The section after the long description contains the tags;
* which provide structured meta-data concerning
* the given element.
* @author Mike van Riel <mike.vanriel@naenius.com>
*
* @since 1.0
*
* @param int $example This is an example description.
* @param string $example2 This is a second example.
*/
Este bloque se divide en los siguientes apartados:
- Descripción corta
- Descripción larga
- Tags
Existen dos tipos principales de DocBlocks. A nivel de fichero y a nivel de elemento. Los bloques a nivel de fichero definen el funcionamiento o el propósito del fichero y los de nivel de elemento comentan una determinada clase o función.
A continuación vamos a ver la forma recomendada de utilizar estos bloques en un fichero de ejemplo.
<?php
/**
* This is a file-level DocBlock
*
* No warning will be raised. This is the recommended usage
* @package SomePackage
*/
/**
* This is a not a file-level DocBlock, because it
* precedes a class declaration
* This is also the recommended usage
* @package SomePackage
*/
class foo {}
?>
Vemos aquí como el primer bloque es a nivel de fichero e indica el atributo de package (paquete). Y el siguiente bloque de documentación se refiere a la clase foo.
Paquetes
El concepto de paquete, como tal, no existe en PHP, pero desde la documentación no es posible indicar un paquete de forma que podamos agrupar conceptos similares. Si especificamos un paquete en el un bloque de documentación todas las funciones, clases, etc serán agrupadas juntas. En el caso de no especificar ningún paquete todo irá al paquete DEFAULT.
Referencias
Comentarios