Hello,

Le sam. 28 sept. 2019 à 12:25, RastaPopoulos <rastapopou...@spip.org> a
écrit :

> Gildas, le YAML sert pas à aller le lire hein… il sert à afficher son
> contenu dans une page, donc bien pour les rédacs, d'où les squelettes
> qui l'affiche. Quand aux docs, ou explications, c'est toujours mieux "in
> situ" qu'en devant aller les chercher/lire ailleurs, un manuel séparé,
> sur un autre site que là où on est en train d'écrire. En théorie une
> interface ergonomique n'a pas besoin de doc, disons le moins possible en
> tout cas, et dès qu'il y a besoin, il faut toujours préférer la placer
> pile au bon endroit où la personne en a besoin.
>
> Autant pour Saisies et Vérifier je vois pas trop l'intérêt car ce n'est
> que pour les développeurs. Mais pour les modèles là c'est important que
> les rédacteurs puissent savoir *au moment d'écrire*, ce qu'ils ont à
> disposition, quels sont les paramètres possibles, etc. On ne devrait
> jamais devoir partir lire ailleurs pour savoir ça, je suis assez d'accord.
>

L'aspect développeur ou pas ne me parait une raison valable pour ne pas
commenter.
Ces derniers temps, par exemple dans N-Core, j'ai adopté une simili
écriture à la PHPDoc pour commenter les modèles ou inclusions comme suit :

[(#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é.
-->]

On pourrait d'ailleurs imaginer de développer une extension à PHPdoc pour
les HTML.

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

Répondre à