Documentation de code javasrcipt en PHP

Apparition d'un nouveau module dans la librairie PHP, codetodoc, qui permet de générer une documentation de code javascript à partir des commentaires. Encore au stade alpha mais les premiers tests sont encourageants.

Cela fait bien deux ans que je souhaitais écrire quelque chose qui me permette :

  • De générer une documentation de code javascript rapidement et simplement.
  • D'interpréter des commentaires formatés à l'aide d'une syntaxe wiki.

J'utilisais jusque là jsdoc-toolkit, mais sans arriver à produire une documentation qui me convienne. Là, alors que d'autres modules de la librairie ont atteint leur maturité, j'ai enfin décidé de me lancer. D'abord en récupérant le travail sur les expressions régulières de codedown et en l'adaptant à mes besoins. Je génère avec cela un type d'objet hiérarchisé que j'utilise ailleurs, DataNode. Enfin, le rendu est assuré par un TPL_Render. Au final, le module codetodoc est constitué comme suit :

  • codedoc.php : script à utiliser en ligne de commande pour générer la documentation d'une série de fichiers.
  • CodeToDoc : convertisseur des commentaires d'un fichier javascript en documentation.
  • CodeBlock : objet représentant un bloc de commentaires.
  • CodeReader : lecteur des commentaires d'un fichier javascript, renvoyant un objet structuré hiérarchiquement.
  • CodeRender : Rendre l'objet de lecture renvoyé par CodeReader, soit en html, soit en syntaxe wiki.
  • CodeTplRender : une extension de TPL_Render mettant à disposition quelques méthodes de formatage spécifiques, comme la création d'une signature de méthode.

En travaillant sur le rendu en syntaxe wiki, j'ai évidemment fait face à la problématique de la balise fin de bloc d'instruction PHP qui mange la nouvelle ligne. Par exemple, si nous écrivons le code suivant :

start
<?php echo "foo"; ?>
bar
<?php echo "baz"; ?>
end
Lignes PHP d'affichage.

Nous obtenons ceci :

start
foobar
bazend
Rendu de l'affichage.

Alors que nous voudrions plutôt :

start
foo
bar
baz
end
Rendu attendu / espéré.

Par contre, quand on a quelque chose du genre :

start
<?php foreach(array('foo','bar','baz') as $item): ?>
<?php echo $item; ?>
<?php endforeach; ?>
end
Lignes PHP d'affichage et de code.

On veut bien que les deux lignes qui construisent la boucle disparaissent, pour obtenir la même chose qu'au-dessus.

Pour corriger la chose, on peut s'amuser à appliquer quelques correctifs, sans que le résultat ne soit totalement prévisible :

$content = preg_replace(
    array("/\<\?php echo(.+)\?\>$/m", "/ +\<\?php(?! echo)(.+)\?\>$/m"),
    array("<?php echo$1?>\n"        , "<?php$1?>"),
    $content
);
Correctifs de formatage d'un code PHP.

Quelques exemples d'utilisation de CodeToDoc d'ici peu...

  • jsdoc-toolkit : générateur de documentation javascript en java (rhino).
  • docdown : générateur de documentation javascript en PHP.
  • YUI Doc : générateur de documentation javascript de la librairie YUI

ACHOUR, Mehdi ; BETZ, Friedhelm ; DOVGAL, Antony, et al.. Manuel PHP. PHP.net, . Hey, où sont mes nouvelles lignes ?