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.
-
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.
-
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.
-
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à.
-
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.