avargas

Imagino que si está leyendo esto, es porque ha leído en alguna parte sobre la importancia de documentar el código, lo mas probable es que (tal como lo hago yo) comprenda que realmente es importante y que además (de nuevo como yo), no lo haga :P por diversas razones, ya sea porque no es para nada divertido tener que documentar aparte de tener que respetar la sintaxis de DocBlock.

Así que si ud es como yo, PHP_DocBlockGenerator llega al rescate, es un generador automático de DocBlock y se encuentra disponible en PEAR

PHP_DocBlockGenerator es un paquete PEAR, en tal sentido hay que tener PEAR instalado, así que lo primero será revisar si lo está:

$ dpkg -l | grep -i pear

Si está instalado debe ver algo como:

ii  php-pear    5.2.10.dfsg.1-1ubuntu1    PEAR - PHP Extension and  Application Repository

Si no lo tiene instalado, entonces simplemente instale el paquete php-pear; continuemos...

Ahora a instalar el PHP_DocBlockGenerator

$ sudo pear install PHP_DocBlockGenerator

Solo esperamos un momento a que descargue las dependencias, el paquete y se configure y listo, ya podemos usarlo:

$ docblockgen elarchivo.php

Un ejemplo del DocBlock generado para una función del código de Mambo

/**
 * Short description for function
 * 
 * Long description (if any) ...
 * 
 * @param  unknown $msgid        Parameter description (if any) ...
 * @param  unknown $msgid_plural Parameter description (if any) ...
 * @param  unknown $msgstr       Parameter description (if any) ...
 * @param  array   $comments     Parameter description (if any) ...
 * @return void    
 * @access public  
 */
function addentry($msgid, $msgid_plural=null, $msgstr=null, $comments=array())
{
    $entry =  new PHPGettext_Message($msgid, $msgid_plural);
    if (!is_null($msgstr)) $entry->setmsgstr($msgstr);
    if (!empty($comments)) $entry->setcomments($comments);
    $this->strings[$msgid] = $entry;
}

Puede aprender mas de las opciones de la herramienta con el comando docblockgen --help