Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier

Pourquoi faire ?

Les bonnes pratiques recommandent d'abord de décrire ce que va faire le code que vous allez écrire, puis ensuite l'écrire, selon un format élégant, lisible et souvent standardisé.

Bon, des fois je ne pratique pas bien ...

J'ai donc cherché un peu partout sur le web un programme qui permette de documenter a posteriori le code produit et qui réponde aux besoins suivants:

Reformatter le code php selon le standard ALLMAN ou K&R
Ajouter les tags phpDoc lorsque ceux-ci sont manquants au dessus des classes, interfaces et fonctions.
Calculer les balises @param des fonctions ainsi documentées.
Eventuellement ajouter la licence (php, bsd, gnu, ...) en début de script.

Si on trouve un peu partout des scripts php qui permettent de reformatter le code php (code beautifier), aucun n'ajoute des tags phpDoc par défaut.

PHP_Beautifier + un filtre maison: phpDoc

Plutôt que tout réécrire, j'ai choisi d'utiliser une librairie existante qui soit suffisament bien conçue pour permettre l'ajout automatique des tags phpDoc.

Mon choix s'est porté sur le script PHP_Beautifier, dans sa version 0.1.14 version candidate à la release. Bien que necessitant les librairies PEAR, il est trés simple de modifier le code source afin de le rendre indépendant de PEAR. Cette page de démonstration utilise d'ailleurs une telle version modifiée.

Ce script est trés interressant car il se base sur les TOKEN PHP et qu'il permet d'ajouter des filtres à executer selon les TOKEN rencontrés. Ainsi un filtre d'indentation ALLMAN, WHITESMITH, K&R, un filtre de formattage PEAR ou encore un filtre de formattage phpBB sont disponibles.

Cette approche de parser, qui fait défaut à d'autres beautifier, permet d'intégrer de façon non intrusive d'autres modes de formattages.

Ma contribution , le filtre phpDoc, consiste à ajouter les tags phpDoc si le TOKEN rencontré est T_ACCESS, T_FUNCTION, T_INTERFACE en appliquant les règles de gestion ci-aprés.

D'autre part, si le premier TOKEN T_OPEN_TAG n'est pas suivi d'un T_COMMENT_DOC ou d'un T_COMMENT alors le filtre insére si demandé une entête de licence PHP,PEAR,APACHE,BSD. Pour ce faire, il faudra simplement indiquer lors de l'execution du phpBeautifier quelle licence inserer (par défaut aucune).

T_OPEN_TAG: Si le TOKEN n'est ni un T_COMMENT_DOC, ni un T_COMMENT on insére le commentaire de licence choisi.
T_ACCESS (public, private, protected + [final, static ]): Si le précédent TOKEN n'est ni un T_COMMENT_DOC, ni un T_ACCESS alors on insére le tags phpDoc par défaut avant la déclaration du T_ACCESS.; On éxamine si la cible est une fonction, une classe ou interface afin de customiser le tag à insérer.
T_CLASS: Si le précédent TOKEN n'est ni un T_COMMENT_DOC, ni un T_ACCESS alors on insére le tags phpDoc par défaut, sinon la règle 1 a déjà fait le travail.
T_FUNCTION: Si le précédent TOKEN n'est ni un T_COMMENT_DOC, ni un T_ACCESS alors on insére le tags phpDoc par défaut, sinon la règle 1 a déjà fait le travail.
T_INTERFACE: Si le précédent TOKEN n'est ni un T_COMMENT_DOC, ni un T_ACCESS on insére le tags phpDoc par défaut, sinon la règle 1 a déjà fait le travail.

An article in english, related to Automatically adding phpDoc tags, using PHP_Beautifier can be found here: A tool to add and complete PHP source code documentation

Exemple d'utilisation

				// Instanciation du beautifier
				$oToken = new PHP_Beautifier(); 
				
				// Ajout de filtres bien sympathiques.
				$oToken->addFilter('ArrayNested');	
				$oToken->addFilter('Lowercase');		
				$oToken->addFilter('IndentStyles',array('style'=>'k&r'));
				
				// Ajout du filtre phpDoc, en demandant d'inserer une
				// licence php au début du fichier.
				$oToken->addFilter('phpDoc',array('license'=>'php'));
				
				// On suppose ici que le code est déja passé
				// dans la variable $sourcecode. A noter qu'une
				// fonction	setInputFile existe,permettant de 
				// passer un nom de fichier à traiter.
				
			    $oToken->setInputString($sourcecode); 		
			    $oToken->process();
				
				//Tada, on récupère le résultat, tout propre ! 					
			    echo $oToken->get();

Telechargements

Démonstration de PHP_Beautifier + phpDoc

Place à la démonstration. Vous trouverez ci-dessous un petit exemple vous permettant de combiner différents filtre phpBeautifier, et bien entendu le filtre phpDoc. Le HighLightSyntax n'est pas réalisé via un filtre, mais par l'utilisation de CodeMirror.

fxnion.free.fr