Remplacer Code par Search (et laisser Search dispo pour autre chose)

[eric_tonton (Eric Lupinacci)]

@rastapopoulos

Et je mets ma main à couper (ça aussi c’est rhétorique ?) que la majorité des recherches de code.spip servent (servaient) à trouver les arguments et la description en français de ces arguments pour telle ou telle fonction

Aie ça va faire mal
Je pense que votre débat part dans une issue parce que je ne suis pas sur qu’on ait posé la bonne question au début du fil. Elle est trop fermée alors que le sujet est plus large.

Moi j’utilise Code.spip sur les plugins principalement, pas le spip car je préfère aller sur Programmer quand l’explication existe - mais elle n’existe pas toujours - et dans le code sinon. Mon utilisation c’est la compréhension de l’API dans son ensemble ce qui me parait pas possible vue de ma fenêtre avec Search qui est impressionnant mais pas forcément intuitif.

Pour les plugins, je l’utilise :

1. Pour avoir une vue globale du plugin (api, balises, critères, etc)
2. Vérifier le phpdoc : complétude, erreurs, etc. Et ça seul une génération de phpdoc peut le fournir. Alors y a peut-être une autre façon de faire avec une installation local ou distante comme un service ?

Donc quoi qu’on décide, Search ne remplace pas Code.spip.
Maintenant, on peut s’adapter si ça permet à certains de se libérer du temps.

Après, on voit aussi que Programmer n’est pas complet au niveau des api et que le code ou le phpdoc est utile. Il ne faut donc pas supprimer sans faire l’effort de complétude où qu’il soit. C’est en sens que je dis que la question initiale n’est pas la bonne.

On a de la chance on est au bon endroit pour en discuter

[marcimat (Matthieu Marcillaud)]

Désolé je n’ai pas tout lu vos commentaires… je vais juste ajouter quelques remarques sur pourquoi je trouve code.spip.net peu pertinent maintenant. Et je suis d’accord avec Eric pour dire que Search ne le remplace pas fondamentalement.

1. avant (une version antérieure de PhpDocumentor que j’avais beaucoup adaptée), on avait une page pour les balises, boucles, critères, etc. qui était extraite, et ça c’était sympa, très spipiennement utile. Ce n’est plus le cas avec les nouvelles versions : je n’ai vraiment pas eu le courage / le temps de refaire ça : l’extraction automatique c’est bien, mais ça ne remplace pas toujours une documentation plus rédigée d’exemples à la mano.

2. maintenant les IDE sont puissants, vraiment… tu ouvres ton dépot git dedans, tu as toutes les infobulles qui montre la définition des fonctions, t’aide à l’auto-complétion… détecte mieux les incohérences que toi-même… C’est incomparable avec il y a quelques années auparavant.

3. les projets git se sont assez structurés et reposent très souvent sur une documentation uniquement intégrée dans le dépot git : le readme et un répertoire docs/ , qui est parfois exporté en site statique. Ça permet de créer des PR pour la doc, de la mettre à jour en même temps que les modifications de code. Si quelque chose devait se structurer à long terme, ça me semble le plus logique. À ce moment là, code.spip ou Contrib pourrait pourquoi pas récupérer ou accéder à ces documentations là.

4. pour les API, il me semble qu’on se fourvoie un peu en pensant essentiellement au code actuel de SPIP. C’est plus simple de considérer en programmation objet, que les classes interfaces, et les fonctions à visibilité publiques sont des APIs… et le reste… bah simplement non. Et les IDE s’en accommodent bien.
   Dans SPIP actuellement tout est plutôt mélangé et des fonctions internes sous prétexte qu’elles ont été utilisées quelque part (simplement parce que par défaut tout est utilisable publiquement) sont devenues considérées comme des entrées possibles, et c’est aussi un problème qui peut limiter les évolutions.

Bref, j’espère que je ne digresse pas.

[eric_tonton (Eric Lupinacci)]

@marcimat

vant (une version antérieure de PhpDocumentor que j’avais beaucoup adaptée), on avait une page pour les balises, boucles, critères, etc. qui était extraite, et ça c’était sympa

Oui absolument, on en avait discuté quand tu avais mis à jour le nouveau code.spip pour lequel j’avais déploré les pertes que tu as citées. Mais c’est vrai que le spécifique c’est lourd à gérer.

@marcimat

les projets git se sont assez structurés et reposent très souvent sur une documentation uniquement intégrée dans le dépot git : le readme et un répertoire docs/ , qui est parfois exporté en site statique.

Oui c’est peut-être une bonne réponse. De mon coté j’ai mis dans mes derniers plugins de type « API pour quelque chose » un guide de conception qui couvre les besoins cités mais qui est aussi assez lourd à maintenir. Maintenant je peux attester que pour revenir une fois par an sur les plugins, c’est d’une efficacité redoutable.
Il serait intéressant d’avoir un fil de discussion sur ce sujet en tout cas.

@marcimat

pour les API, il me semble qu’on se fourvoie un peu en pensant essentiellement au code actuel de SPIP. C’est plus simple de considérer en programmation objet, que les classes interfaces, et les fonctions à visibilité publiques sont des APIs… et le reste… bah simplement non

Là on diverge. La programmation objet ne peut pas être la seule à proposer une logique d’API car c’est trop technique. comme approche Il nous faut documenter nos api a minima pour dire que tout ce qui n’est pas documenté n’en est pas.
On a eu le cas avec extraire_trads() en spip 5.0. Le fait que l’on réduise la liste des api ne me pose pas de souci si on l’établit clairement et que cela a du sens au niveau de l’utilisateur.
C’est pourquoi que je pense que pour SPIP 5.0 c’est un chantier prioritaire que de définir nos api qu’elles soient en POO ou pas.

[rastapopoulos]

@marcimat

je vais juste ajouter quelques remarques sur pourquoi je trouve code.spip.net peu pertinent maintenant. Et je suis d’accord avec Eric pour dire que Search ne le remplace pas fondamentalement.

Bé oui oui, c’est exactement ce que j’ai dit… depuis le tout début

C’est-à-dire que :

• j’ai bien dit dès le tout premier message que ça faisait pas 100% pareil
• les IDE et/ou Sourcegraph additionnés permettent néanmoins de couvrir la majorité de ce que la plupart venait chercher sur code.spip (« comment utiliser telle ou telle fonction »)
• la vraie doc humaine, choisissant des exemples concrets et/ou des tutoriels est irremplaçable pour aller plus loin que le phpdoc automatique (que montrent IDE + Sourcegraph), mais ça c’est dans Programmer justement (et Contrib pour les plugins, et les Readme)
• en conséquence de quoi, code.spip ne semblant avoir quasiment plus aucune utilité pour ce qu’on venait y chercher (remplacé par IDE + Sourcegraph + les vraies docs), mon point de vue était qu’il serait plus clair de montrer « la recherche dans Tout Le Code » (et pas juste core et quelques plugins triés) sur le domaine code.spip en le remplaçant, plus utile et plus clair pour la plupart des gens
• et du coup pour les non-connoisseurs et les gens de passage, avoir moins de possibilité de s’y perdre, en n’ayant plus qu’une entrée dans le menu, ayant rapport au code automatisé (sourcegraph sur code.spip), et une entrée de vraie doc de chaque type (programmer.spip pour le core, et contrib.spip pour les plugins, lui-même fusionnant deux sites pour simplifier)