Una herramienta para añadir y completar la documentación del código fuente PHP [cerrado]

Creo PHP_Codesniffer puede indicar cuando no hay ningún bloque de documentación-ver los ejemplos de informes sobre esta página (citando a uno de esos) :

--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR   | Missing file doc comment
 20 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE"
 47 | ERROR   | Line not indented correctly; expected 4 spaces but found 1
 47 | WARNING | Equals sign not aligned with surrounding assignments
 51 | ERROR   | Missing function doc comment
 88 | ERROR   | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

Supongo que podría usar PHP_CodeSniffer para al menos obtener una lista de todos los archivos / clases / métodos que no tienen documentación; por lo que recuerdo, puede generar XML como salida, lo que sería más fácil de analizar usando alguna herramienta automatizada that que podría ser el primer paso de algún docblock-generator ;-)

Además, si está utilizando phpDocumentor para generar la documentación, ¿puede este no reportar errores por bloques faltantes ?

Después de un par de pruebas, puede running por ejemplo, ejecutarlo en un archivo de clase con poca documentación, con la opción --undocumentedelements, como esta :

phpdoc --filename MyClass.php --target doc --undocumentedelements

Da esto en el medio de la salida:

Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file
WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock.
WARNING in MyClass.php on line 2: no @package tag was used in a DocBlock for class MyClass
WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock.
WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use @package in the first DocBlock to create one
done

Pero, aquí, también, incluso si es útil como herramienta de informes, no es tan útil cuando se trata de generando los docblocks faltantes...

Ahora, no conozco ninguna herramienta que pre-genere los docblocks faltantes para usted : generalmente uso PHP_CodeSniffer y / o phpDocumentor en mi mecanismo de integración continua, reporta docblocks faltantes, y, luego, cada desarrollador agrega lo que falta, desde su IDE...

... Lo que funciona bastante bien: generalmente no hay más de un par de docblocks faltantes todos los días, por lo que la tarea se puede hacer a mano (y Eclipse PDT proporciona una característica para pre-generar el docblock para un método, cuando se está editando un archivo/método específico) .

Aparte de eso, realmente no conozco ninguna herramienta totalmente automatizada para generar docblocks... Pero estoy bastante seguro de que podríamos crear una herramienta interesante, usando cualquiera de los dos :

• La API de Reflexión
• token_get_all para analizar el origen de un archivo PHP.

Después de un poco más de búsqueda, sin embargo, encontré esto blog-post (está en francés maybe tal vez algunas personas aquí serán capaces de entender) : Ajout automatique de Tags PHPDoc à l'aide de PHP_Beautifier .
Posible traducción del título:"Adición automática de etiquetas PHPDoc, usando PHP_Beautifier"

La idea en realidad no es mala:

• El PHP_Beautifier la herramienta es bastante agradable y poderosa, cuando se trata de formatear algún código PHP que no está bien formateado
  • Lo he usado muchos tiempos para el código que ni siquiera podía leer ^^
• Y se puede extender, usando lo que llama " filtros".
  • véase PHP_Beautifier_Filter para una lista de filtros proporcionados

La idea que se usa en el blog-post al que enlacé es:

• cree un nuevo filtro PHP_Beautifier, que detectará los siguientes tokens :
  • T_CLASS
  • T_FUNCTION
  • T_INTERFACE
• Y añádase un " borrador" doc-bloquear justo antes de ellos, si no hay ya uno

Para ejecutar la herramienta en algún archivo MyClass.php, primero tuve que instalar PHP_Beautifier:

pear install --alldeps Php_Beautifier-beta

Luego, descargue el filtro al directorio en el que estaba trabajando (podría haberlo puesto en el directorio predeterminado, por supuesto) :

wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs
cp phpDoc.filter.phpcs phpDoc.filter.php

Y, después de eso, creé un nuevo script beautifier-1.php (Basado en lo que se propone en el blog-post al que enlacé, una vez más), que :

• Cargar el contenido de mi archivo MyClass.php
• Instancias PHP_Beautifier
• Añadir algunos filtros para embellecer el código
• Añade el filtro phpDoc que acabamos de descargar
• Embellecer la fuente de nuestro archivo, y hacer eco a la salida estándar.

Al código del script beautifier-1.php le gustará esto :
(Una vez más, la parte más grande es un copy-paste de la entrada del blog; solo traduje los comentarios y cambié un par de cosas pequeñas)

require_once 'PHP/Beautifier.php';

// Load the content of my source-file, with missing docblocks
$sourcecode = file_get_contents('MyClass.php');

$oToken = new PHP_Beautifier(); 

// The phpDoc.filter.php file is not in the default directory,
// but in the "current" one => we need to add it to the list of
// directories that PHP_Beautifier will search in for filters
$oToken->addFilterDirectory(dirname(__FILE__));

// Adding some nice filters, to format the code
$oToken->addFilter('ArrayNested');  
$oToken->addFilter('Lowercase');        
$oToken->addFilter('IndentStyles', array('style'=>'k&r'));

// Adding the phpDoc filter, asking it to add a license
// at the beginning of the file
$oToken->addFilter('phpDoc', array('license'=>'php'));

// The code is in $sourceCode
// We could also have used the setInputFile method,
// instead of having the code in a variable
$oToken->setInputString($sourcecode);        
$oToken->process();

// And here we get the result, all clean !              
echo $oToken->get();

Nota que también tuve que trazar dos pequeñas cosas en phpDoc.filter.php, para evitar una advertencia y un aviso...
El parche correspondiente se puede descargar allí: http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch

Ahora, si ejecutamos ese script beautifier-1.php:

$ php ./beautifier-1.php

Con un archivo MyClass.php que contiene inicialmente este código :

class MyClass {
    public function __construct($myString, $myInt) {
        // 
    }

    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...
    }

    protected $_myVar;
}

Este es el tipo de resultado que obtenemos once una vez que nuestro archivo está Embellecido :

<?php
/**
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to [email protected] so we can mail you a copy immediately.
 * @category   PHP
 * @package
 * @subpackage Filter
 * @author FirstName LastName <mail>
 * @copyright 2009 FirstName LastName
 * @link
 * @license     http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 */


/**
 * @todo Description of class MyClass
 * @author 
 * @version 
 * @package 
 * @subpackage 
 * @category 
 * @link 
 */
class MyClass {

    /**
     * @todo Description of function __construct
     * @param  $myString 
     * @param  $myInt
     * @return 
     */
    public function __construct($myString, $myInt) {
        //

    }
    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...

    }

    protected $_myVar;
}

Podemos notar: {[39]]}

• La licencia bloque al principio del archivo
• El docblock que se ha añadido en la clase MyClass
• El docblock que se ha añadido en el método __construct
• El docblock en el doSomething ya estaba presente en nuestro código : no se ha eliminado.
• Hay algunas etiquetas @todo ^^

Ahora, no es perfecto, por supuesto :

• No documenta todas las cosas que podríamos querer también
  • Por ejemplo, aquí, no documentó la protected $_myVar
• No mejora los docblocks existentes
• Y no abre el archivo en ningún editor gráfico
  • Pero eso sería mucho más difícil, supongo...

Pero estoy bastante seguro de que esta idea podría usarse como punto de partida para algo mucho más interesante :

• Sobre las cosas que no se documentan: agregar nuevas etiquetas que se reconocerán no debería ser demasiado difícil
  • Usted acaba de tener para añadirlos a una lista al principio del filtro
• Mejorar los docblocks existentes podría ser más difícil, tengo que admitir
• Lo bueno es que esto podría ser totalmente automatizado{[66]]}
• Usando Eclipse PDT, tal vez esto podría establecerse como una Herramienta externa , por lo que al menos podemos lanzarlo desde nuestro IDE ?