Hello,

> Le 2 oct. 2019 à 09:10, Eric Lupinacci <e...@smellup.net> a écrit :
> 
> Hello,
> 
> 
> 
> Le lun. 30 sept. 2019 à 12:27, Mist. GraphX <arnaud.ber...@mister-graphx.com 
> <mailto: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 
> <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...
> 

Est-ce qu’il y aura une fonction permettant d’extraire cette documentation ? 
Sortir un tableau ou autre pour pouvoir faire un rendu html dans l’espace privé.
> 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 <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

Ybbet
> 
> ----
> spip-zone@rezo.net - https://listes.rezo.net/mailman/listinfo/spip-zone

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

Répondre à