au moment de la validation, avec des contraintes indiquées par des classes spécifiques.
Une erreur dans phpDocumentor fait que certaines erreurs sur les tags `@param` ne sont
pas compatibilisées et du coup, j'avais une fonction pour les ajouter, mais pas
dans la méthodologie attendue par phpDocumentor, ce qu'il fait qu'elles apparraissent
en double.
Après une (assez longue) analyse, la source du problème qui fait que phpDocumentor
n'analysait pas certaines erreurs est trouvée, et un patch est proposé
(https://github.com/phpDocumentor/phpDocumentor2/issues/1677)
En attendant son intégration un jour éventuel, on envoie ici,
sous le bon format de quoi trouver les erreurs en question.
Et on nettoie au passage l'ancien mécanisme que j'utilisais.
Cependant, on tolère de mettre des @see ou @uses vers des fonctions de SPIP.
Dans ce cas là, un lien sera fait vers code.spip.net.
On ne pourra trouver que les fonctions présentes dans code.spip.net,
c'est à dire dans la version de SPIP en développement.
De même, alternativement, --topnav=URL ajoutera le js contenu dans l'url indiquée dans le header.
Exemple : `autodoc/bin/autodoc_helper from:file --avec_boussole_spip`
Génère la documentation des plugins de la zone, avec la boussole intégrée.
En fait, phpdocumentor attend : @example url [start?] [stop?] [description?]
mais nous on écrit simplement : @example texte d'exemple
qui ne correspond pas à une url. Le premier mot ou suite de caractères avant un espace
est considéré comme l'url (inexistante), et ne fait pas partie de la description.
Donc, on remet l'url fausse, dans la description, avec start et stop (numéro de première ligne et nombre de ligne)
s'ils avaient aussi été capturés par hasard des textes.
Nombreuses adaptations :
1) les binaires sont maintenant sans extension .php
2) Pour tenir compte des <options> que l'ont passait dans phpdoc.xml, spécifique à l'autodoc,
il faut grandement ruser maintenant car le sérialiseur / désérialiseur utilisé maintenant par phpdocumentor
ne conserve que les éléments qui lui sont déclarés. Pour cela, on surcharge donc la classe Configuration
de phpdocumentor pour ajouter notre tableau d'options.
À noter que la syntaxe est légèrement différente (voir Helpers/phpdoc_helper.xml)
3) Pour faire parvenir les données de configuration au template Twig, et suite toujours au
changement dans la gestion de la configuration de phpdocumentor, on transmet directement
aux template la configuration connue (sans la recalculer). Mais pour cela, on doit
surcharger le Writer/Twig pour ajouter notre élément. La surcharge est minime heureusement.
4) L'autoloader est déclaré différemment également. Il est appelé avant le chargement de phpDocumentor
et lui est transmis lors de la création (new Application(...)). On s'adapte (dans bin/autodoc) et on
adapte toutes les commandes Helpers pour transmettre cet autoloader… Pfiou.
Du coup, pour simplifier un peu, on crée une Application pour le Helpers, et on déporte
de bin/autodoc_helper vers l'application la déclaration des commandes utilisables.
Matthieu Marcillaud
marcimat@rezo.net