Un outil pour ajouter et compléter la documentation du code source PHP [fermé]

Je pense PHP_Codesniffer peut indiquer quand il n'y a pas de docblock-voir les exemples de rapports sur cette page (citant l'un de ces) :

--------------------------------------------------------------------------------
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
--------------------------------------------------------------------------------

Je suppose que vous pourriez utiliser PHP_Codesniffer pour au moins obtenir une liste de tous les fichiers / classes / méthodes qui n'ont pas de documentation; d'après ce que je me souviens, il peut générer XML en sortie, ce qui serait plus facile à analyser en utilisant un outil automatisé - cela pourrait être la première étape d'un générateur de docblock ;-)

De plus, si vous utilisez phpDocumentor pour générer la documentation, celle-ci peut-elle ne pas signaler d'erreurs pour les blocs manquants ?

Après quelques tests, il peut-par exemple, l'exécuter sur un fichier de classe avec peu de documentation, avec l'option --undocumentedelements, comme ceci:

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

Donne ceci au milieu de la sortie:

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

Mais, ici aussi, même si c'est utile comme outil de reporting, ce n'est pas très utile quand il s'agit de générer les éléments manquants...

Maintenant, je ne connais aucun outil qui va pré-générer les docblocks manquants pour vous: j'utilise généralement PHP_Codesniffer et / ou phpDocumentor dans mon mécanisme d'intégration continue, il signale les docblocks manquants, et, ensuite, chaque développeur Ajoute ce qui manque, de son IDE...

... Ce qui fonctionne assez bien : il n'y a généralement pas plus de quelques docblocks manquants tous les jours, donc la tâche peut être faite à la main (et Eclipse PDT fournit une fonctionnalité pour pré-générer le docblock pour une méthode, Lorsque vous modifiez un fichier/méthode spécifique) .

En dehors de cela, je ne connais pas vraiment d'outil entièrement automatisé pour générer des docblocks... Mais je suis sûr que nous pourrions réussir à créer un outil intéressant, en utilisant soit:

• L'API de réflexion
• token_get_all pour analyser la source d'un fichier PHP.

Après un peu plus de recherche, cependant, j'ai trouvé ce blog-post (c'est en français -- peut-être que certaines personnes ici pourront comprendre) : Ajout automatique de Tags phpDoc à L'aide de PHP_Beautifier .
traduction Possible du titre: "ajout automatique de balises phpDoc, en utilisant PHP_Beautifier"

L'idée n'est en fait pas mauvaise:

• Le PHP_Beautifier l'outil est assez agréable et puissant, quand il s'agit de formater du code PHP qui n'est pas bien formaté
  • Je l'ai utilisé beaucoup fois pour le code que je ne pouvais même pas lire ^ ^
• et il peut être étendu, en utilisant ce qu'il appelle " filtres ".
  • voir PHP_Beautifier_Filter pour une liste de filtres fournis

L'idée qui est utilisée dans le blog-post que j'ai lié est de:

• créez un nouveau filtre PHP_Beautifier, qui détectera les jetons suivants :
  • T_CLASS
  • T_FUNCTION
  • T_INTERFACE
• et Ajouter un " projet" doc-block juste avant eux, s'il n'y en a pas déjà un

Pour exécuter l'outil sur un fichier MyClass.php, j'ai d'abord dû installer PHP_Beautifier:

pear install --alldeps Php_Beautifier-beta

Ensuite, téléchargez le filtre dans le répertoire, j'ai travaillé dans (pourrait l'avoir mis dans le répertoire par défaut, bien sûr) :

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

Et, après cela, j'ai créé un nouveau script beautifier-1.php (basé sur ce qui est proposé dans le blog-post auquel j'ai lié, encore une fois) , qui sera:

• charger le contenu de mon fichier MyClass.php
• Instancier PHP_Beautifier
• ajoutez des filtres pour embellir le code
• ajoutez le filtre phpDoc que nous venons de télécharger
• embellissez la source de notre fichier et faites-la écho à la sortie standard.

Le code du script beautifier-1.php aimera ceci :
(encore une fois, la plus grande partie est un copier-coller du billet de blog ; j'ai seulement traduit les commentaires, et changé quelques petites choses)

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();

Note que j'ai aussi dû tracer deux petites choses dans phpDoc.filter.php, pour éviter un avertissement et un avis...
le patch correspondant peut y être téléchargé: http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch

Maintenant, si nous exécutons ce script beautifier-1.php:

$ php ./beautifier-1.php

Avec un fichier MyClass.php qui contient initialement CE code:

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

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

    protected $_myVar;
}

Voici le genre de résultat que nous obtenons-une fois que notre fichier est embelli:

<?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 license@php.net 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;
}

On peut noter:

• la licence bloc au début du fichier
• le docblock qui a été ajouté sur la classe MyClass
• le docblock qui a été ajouté sur la méthode __construct
• le docblock sur le doSomething était déjà présent dans notre code: il n'a pas été supprimé.
• Il y a quelques balises @todo ^ ^

Maintenant, ce n'est pas parfait, bien sûr:

• Il ne documente pas tout ce que nous pourrions le vouloir aussi
  • par exemple, ici, il n'a pas documenté le protected $_myVar
• Il n'améliore pas les docblocks existants
• et il n'ouvre le fichier dans aucun éditeur graphique
  • mais ce serait beaucoup plus difficile, je suppose...

Mais je suis sûr que cette idée pourrait être utilisée comme point de départ pour quelque chose de beaucoup plus intéressant:

• A propos des choses qui ne sont pas documentées: ajouter de nouvelles balises qui seront reconnues ne devrait pas être trop difficile
  • Vous avez juste pour les ajouter à une liste au début du filtre
• améliorer les docblocks existants pourrait être plus difficile, je dois admettre
• une bonne chose est que cela pourrait être entièrement automatisé
• en utilisant Eclipse PDT, peut-être que cela pourrait être défini comme un outil externe , afin que nous puissions au moins le lancer à partir de notre IDE ?