veilletech.frCe qui se passe
Twig sait déjà déclarer les types attendus par un template, via la balise
types. Ce qu'il ne savait pas faire, c'est dire ce que ces variables
représentent.
Twig 3.29 ajoute les documentation comments : une syntaxe standard pour attacher une description lisible à une construction du template. La contribution vient de Fabien Potencier.
Le problème que ça résout
Les projets qui documentent une API de templates — typiquement une bibliothèque
de composants — s'en remettent aujourd'hui à des conventions maison glissées
dans des commentaires Twig ordinaires : des annotations du genre @prop ou
@block.
Deux défauts, cumulés :
- elles répètent des noms et des types déjà déclarés dans la balise
types, ce qui crée deux sources de vérité qui divergent ; - elles obligent chaque IDE, chaque analyseur statique et chaque générateur de documentation à comprendre un format propre au projet.
Comment ça marche
La syntaxe reprend les délimiteurs de commentaire Twig habituels, avec un dièse supplémentaire. Le commentaire s'associe à la construction qui suit immédiatement : une expression de sortie, une balise native ou personnalisée, un bloc, une macro. Des commentaires de documentation consécutifs sont combinés, ce qui évite d'écrire une ligne interminable.
À l'intérieur d'une balise, la forme est différente : la documentation commence par deux dièses et court jusqu'à la fin de la ligne. C'est ce qui permet de décrire une déclaration au plus près, sans répéter son nom ni son type.
Ce mode inline a une conséquence syntaxique à connaître : comme le commentaire consomme le reste de la ligne, la variable qu'il décrit doit commencer sur une ligne suivante. Un commentaire placé dans une position non supportée reste un commentaire ordinaire et n'expose aucune métadonnée — il ne casse rien, il est simplement ignoré.
La syntaxe types existante ne change pas : les variables requises gardent leur
nom nu, les optionnelles gardent leur suffixe ?. La documentation est une
métadonnée additionnelle associée à chaque déclaration.
Ce que ça change pour l'outillage
Le rendu n'est pas touché. Twig ne fait qu'attacher le contenu du commentaire
aux nœuds analysés, où un node visitor peut le récupérer avec
Node::getDocumentation().
C'est le point important : cela donne à tout l'écosystème une source commune
de métadonnées. Un IDE peut afficher la description pendant l'autocomplétion,
un analyseur statique l'inclure dans ses diagnostics, un générateur construire
une référence d'API directement depuis le template. Symfony Language Tools,
le serveur LSP officiel sorti la semaine dernière, les comprend déjà : pour les
variables déclarées via types, complétion et survol affichent le type, le
caractère requis ou optionnel, et la documentation attachée.
Les réserves
Deux, et elles sont explicites dans l'annonce.
La fonctionnalité est expérimentale en 3.29. La syntaxe et l'API de métadonnées peuvent évoluer selon les retours des auteurs de templates et des développeurs d'outillage. À utiliser, donc, mais sans construire de génération de documentation critique dessus dès aujourd'hui.
La dégradation, en revanche, est propre. Les versions antérieures de Twig
analysent ces blocs comme des commentaires ordinaires, et Twig 3.15 et suivants
traitent déjà ## dans une balise comme un commentaire inline. Un template
peut donc adopter la syntaxe sans changer son rendu sur les versions plus
anciennes.