Hello,


Le lun. 30 sept. 2019 à 12:27, Mist. GraphX <arnaud.ber...@mister-graphx.com>
a écrit :

> Bon comme tout les commentaires sont partis sur des solutions purement
> developpeur php a base de php doc et truc dans le genre, je vais rajouter
> ma vision d’intégrateur qui ne voit donc que le coté front !
>
Ca c'est le genre de phrase qui a le don de me foutre en rogne.
A aucun moment le problème a été posé de cette façon, le sujet n'a été que
d'analyser si il y avait une façon commune de remplir le besoin sachant
qu'en PHP on y répond déjà via le PHPDoc.
Et sachant qu'il n'y aucune différence pour un développeur ou un
utilisateur sur le niveau d'information requis pour utiliser un modèle ou
une inclusion (c'est la liste commentée des paramètres en gros), ma
proposition était d'utiliser un langage commun et un format commun à
l'intérieur du fichier lui-même et pas à l'extérieur via du YAML et donc
d'utiliser un simili-phpdoc parce qu'on l'utilise déjà ailleurs (donc
apprentissage simplifié).


> *Alors je vais revenir une enième fois a la charge … ^^*
>
> Depuis quelques années maintenant, j’utilise Kss comme méthodologie pour
> documenter mes css/scss markup (le theme) et ceci est basé sur les
> commentaires avec un parser de comments qui est déjà prévu pour ça avec un
> nomenclature simple. L’état actuel des modèles et les sections commentaires
> de la plupart est quasiement déjà au bon format. On peut le voir sur par
> exemple les modèle de owl-carousel, ils sont déjà au format kss (pour cause
> ^^), mais dans d’autres modèles d’autres plugins aussi c’est similaire.
>
>
> [(#REM)<!-- # Owl Video player
>
> VideoPlayer avec Owl Carousel et oembed
>
> @see - http://owlgraphic.com/owlcarousel/index.html#customizing
> @param objet -
> @param id_objet -  lister les medias vidéos associés a un objet/id_objet
> @param id_document {array} - peut être un tableau de documents
> @param id-carousel - selecteur id unique du carousel
> @param navigation {str} (oui|non) - affiche les boutons précédents suivants
> @param dots {str} (oui|non) - affiche les point de navigation
> @param : lazyLoad : true (false par défaut) : ne charge que les images 
> visibles pour optimiser le chargement.
> @param afficher_thumbnails {str} (oui|non) - Affichage des miniatures de 
> navigation
> @param thumbs_loop {str} (oui|non) - Rotation infinie des miniatures
> @param animateIn - une animation css3 , `fadeOut` est la seul fournie par 
> owl, sinon ajouter animate.css
> @param animateOut - une animation css3 , `fadeOut` est la seul fournie par 
> owl, sinon ajouter animate.css
> @todo - Corriger : en mode touch/drag le player vidéo n'est pas détruit du 
> coup plusieurs vidéos peuvent jouer en mm temps
> -->]
>
> En quoi cette façon de faire n'est pas un simili-phpdoc ?
J'avais donné l'exemple suivant :

[(#REM) <!--  CONTENEUR_COMPILER

   Compile les noisettes d'un conteneur fourni en paramètre de l'inclusion.
   Cette inclusion est utilisée pour compiler récursivement une
noisette conteneur.
   Elle peut être surchargée pour s'adapter au mieux au stockage du
plugin utilisateur.

   @api

    @param string plugin
           Identifiant qui permet de distinguer le module appelant qui
peut-être un plugin comme le noiZetier ou
           un script. Pour un plugin, le plus pertinent est d'utiliser
le préfixe.
   @param string  id_conteneur
          Identifiant du conteneur.
   @param string stockage
           Identifiant du service de stockage à utiliser si précisé.
-->]

Je trouve qu'il y a des similitudes non ;-) ?
En tout cas, oui ça me parait être la solution la plus pertinente et si en
plus elle est déjà outillée...

J’ai déjà fait des tests il y’a quelques temps dans ce sens, et j’avais
> commencé une intégration de la lib en plugin spip, pour les styles, mais
> voyant que en en parlant ça ne defrayait pas non plus un engouement
> terrible ;-) , j’ai préféré continué sur un dev hors spip plus polyvalent
> dans mon cas. Cela dit c’est une lib php et des class et ça retourne un
> objet donc rien de bien dur a renvoyer a un template spip.
>
> https://github.com/kss-php/kss-php
>
> il y’a quelques modifications minimes a faire dans le parser pour que les
> commentaires spip soient pris en charge, prendre en charge le format html
> et adapter la regex des comments a spip, mais comme c’est une classe ça
> s’étend facilement.
>
> bref au final on est pas loin de la syntaxe des phpdoc ou javadoc et on
> pourrait documenter dans le html, ce qui reste de mon avis la solution la
> plus simple et efficace.
>
Oui, je suis d'accord.
Et je pense que ça pourrait permettre aussi d'intégrer les inclusions dans
la documentation générée par Autodoc moyennant une adaptation.

++
Eric
----
spip-zone@rezo.net - https://listes.rezo.net/mailman/listinfo/spip-zone

Répondre à