Hello,
Pourquoi avoir fait ça pour tous les plugins dist ?
Je ne suis pas sur que ce soit très lisible pour tous.
J’aurais plutôt fait ça au coup par coup.
Le 19/02/2018 à 15:11, Eric Lupinacci a écrit :
Hello,
Pourquoi avoir fait ça pour tous les plugins dist ?
Je ne suis pas sur que ce soit très lisible pour tous.
J'aurais plutôt fait ça au coup par coup.
On peut aussi se dire que justement, c'est de l'automatisme et ce sont
les plugins officiels, dont on génère leur doc, et si celle-ci n'est pas
bien rédigée, pas bien complète, bah ça pousse à l'améliorer, plutôt que
d'afficher un truc que quand il est super bien terminé (ce cas peut se
comprendre pour un plugin en dev ou test, pas fignolé, mais là on parle
des plugins distribués et maintenus par le core).
--
RastaPopoulos
Oui c’est aussi possible.
Maintenant il y a des plugins qui ont peu d’intérêt car ils ne possèdent aucune API voire fonction.
En tout cas, il faut dire clairement que le phpdoc dans cette liste est maintenant de tout niveau.
Le 19/02/2018 à 15:11, Eric Lupinacci a écrit :
Hello,
Pourquoi avoir fait ça pour tous les plugins dist ?
Je ne suis pas sur que ce soit très lisible pour tous.
J'aurais plutôt fait ça au coup par coup.
Oui, si le phpdoc n'est pas bien propre, ça va être contre productif et donner une mauvaise doc.
--
nicod_
Le 20/02/2018 à 11:22, nicod_ a écrit :
Le 19/02/2018 à 15:11, Eric Lupinacci a écrit :
Hello,
Pourquoi avoir fait ça pour tous les plugins dist ?
Je ne suis pas sur que ce soit très lisible pour tous.
J'aurais plutôt fait ça au coup par coup.Oui, si le phpdoc n'est pas bien propre, ça va être contre productif et donner une mauvaise doc.
Tu as un exemple de "mauvaise doc" "contreproductive" ?
Sur 'vérifier' par exemple, il y a 0 phpdoc,
mais ça fait quand même une belle page de doc :
https://code.plugins.spip.net/verifier/tree/verifier_fonctions.php.html
JL
C’est génial on apprend beaucoup avec cette page 
!
Je suis d’accord avec nicod, je pense que le PHPDoc n’apporte quelque chose que si il est à jour.
Et quand on dit à jour c’est pas une fois au début mais après chaque modification si besoin.
Espérons que des vocations vont naitre pour mettre à jour le PHPDoc des plugins-dist.
(tiens ça me rappelle un truc…)
Le 20/02/2018 à 18:57, JLuc a écrit :
Sur 'vérifier' par exemple, il y a 0 phpdoc,
mais ça fait quand même une belle page de doc :
https://code.plugins.spip.net/verifier/tree/verifier_fonctions.php.html
Une "belle" page de doc ?
Tu parles du squelette et de l'habillage, ou bien du contenu ?
Parce que tout ce que je vois c'est "Liste des erreurs"...
C'est pas super engageant, et c'est ce que je voulais dire par "contre productif".
--
nicod_
Le 21/02/2018 à 01:09, nicod_ a écrit :
Le 20/02/2018 à 18:57, JLuc a écrit :
Sur 'vérifier' par exemple, il y a 0 phpdoc,
mais ça fait quand même une belle page de doc :
https://code.plugins.spip.net/verifier/tree/verifier_fonctions.php.htmlUne "belle" page de doc ?
Tu parles du squelette et de l'habillage, ou bien du contenu ?
Tout ça ! C'est un agréable point d'entrée,
qui présente des infos synthétiques (la signature de la fonction)
d'un intérêt limité mais qu'on ne trouve nulle par ailleurs
(le source n'étant évidemment pas synthétique)
et un lien vers le source détaillé.
Parce que tout ce que je vois c'est "Liste des erreurs"...
C'est pas super engageant, et c'est ce que je voulais dire par "contre productif".
En effet.
Par contre c'est pas inutile puisque ça pointe ce qu'il reste à faire
comme une todolist.
Pour que ça soit plus engageant à le faire, il faudrait mieux manifester ça,
par exemple en changeant le titre qui à la place de "Liste des erreurs",
pourrait être : "Liste des points sur lesquels améliorer le phpdoc".
JL
Le 21/02/2018 à 08:16, JLuc a écrit :
Le 21/02/2018 à 01:09, nicod_ a écrit :
Le 20/02/2018 à 18:57, JLuc a écrit :
Sur 'vérifier' par exemple, il y a 0 phpdoc,
mais ça fait quand même une belle page de doc :
https://code.plugins.spip.net/verifier/tree/verifier_fonctions.php.htmlUne "belle" page de doc ?
Tu parles du squelette et de l'habillage, ou bien du contenu ?Tout ça ! C'est un agréable point d'entrée,
qui présente des infos synthétiques (la signature de la fonction)
d'un intérêt limité mais qu'on ne trouve nulle par ailleurs
(le source n'étant évidemment pas synthétique)
et un lien vers le source détaillé.Parce que tout ce que je vois c'est "Liste des erreurs"...
C'est pas super engageant, et c'est ce que je voulais dire par "contre productif".En effet.
Par contre c'est pas inutile puisque ça pointe ce qu'il reste à faire
comme une todolist.
Pour que ça soit plus engageant à le faire, il faudrait mieux manifester ça,
par exemple en changeant le titre qui à la place de "Liste des erreurs",
pourrait être : "Liste des points sur lesquels améliorer le phpdoc".JL
----
spip-zone@rezo.net - http://listes.rezo.net/mailman/listinfo/spip-zone
Helloo,
C'est sur que comme disait Rastapopoulos, si on voit rien, on voit pas ce qu'il faut améliorer …
tout le monde n'as pas forcément l'installation de autodoc pour pouvoir travailler en réel la documentation et au final publié quelque chose de propre du premier coup, donc la ça peut aider je pense à faire un état des lieux, mais dans une logique de progressive enhancement (comme on dit ^^).
cela dit la je regarde la, pour la dist qui est un squelette et n'a pas d'api ou de fonctions ça n'as pas vraiment d'intérêt, cela dit on peut la documenter via d'autres méthodes plus adaptées (j'ai déjà évoqué le sujet ^^, mais ça sort du cadre du fil de discussion).
--
Bonne journée
Arnaud B. (Mist. GraphX)