Documentation des APIs de SPIP - commentaires

Documentation des APIs de SPIP

Oui absolument.

En fait, APIS ne distingue pas les fonctions au chargement. C'est uniquement le squelette du site qui le ferait. Donc avec APIS le privé permet de voir et modifier l'ensemble des fonctions publiques et privées.

Il est donc tout à fait possible d'avoir une option aussi dans le site pour voir les fonctions privées. Mais il faut bien comprendre que l'un des objectifs est de favoriser l'utilisation d'une couche d'APIs réduite et donc de faciliter à terme la compatibilité.

Documentation des APIs de SPIP

La conversation est fort intéressante. J'essaie de la prendre en cours (ainsi que sur la liste SPIP-Zone).

Bravo déjà pour cette initiative. Juste une petite question naïve concernant APIS. Si j'ai bien compris, le site public serait limité aux fonctions dites publiques. Quid des autres fonctions ? seraient-elles visibles (pour ceux qui en ont besoin) dans l'espace privé ou via une option à activée sur le site publique ? Dans certains cas, c'est fort pratique de pouvoir rechercher aussi parmi elles.

Amicalement

Documentation des APIs de SPIP

Non au contraire je pense que c'est une fonction essentielle mais peut-être tu ne vois exactement de quoi je parle.

Dans le phpdoc généré tu as :

des informations qui viennent du code (le prototype des fonctions),
et des informations qui sont purement des commentaires

Il est probable qu'il y aura des informations erronées dans les commentaires : type d'argument erroné, description courte ou longue fausse ou incomplète, erreurs d'orthographe... Quand on s'en rend compte dans le site de doc, il est simple de le corriger sur le moment puisque l'outil le permet. Aussi pouvoir générer l'en-tête phpdoc modifiée me parait essentiel pour ne pas faire deux fois le boulot et éviter d'autres erreurs.

De toute façon, la réinjection est manuelle ensuite et correspond uniquement aux champs inclus naturellement dans le phpdoc pas aux champs supplémentaires de la doc.

Pour ce qui est des plugins j'y ai déjà répondu : oui, les plugins peuvent être intégrés dans cette démarche comme des projets séparés.

Documentation des APIs de SPIP

Je crois que tu as mal lu Gilles : seules les entêtes principales seraient réinjectées dans le code, lorsque désiré. C'est-à-dire le titre, la description principale, la description de chaque argument, et la description du retour. Les éléments plus complets (exemples etc) resteraient uniquement dans le site.

Cela permet un truc essentiel : l'aide à la documentation par les AUTRES, que les très rares qui peuvent commiter dans le core. Et même pas les non développeurs, ce qui est encore mieux.

Documentation des APIs de SPIP

Oui, je suis d'accord.
Juste une chose d'ailleurs. Les plugins APIS et Autodoc sont fait pour recevoir des « projets » de documentation. Donc SPIP est un projet comme un autre, ce qui veut dire que ce site pourrait supporter à la fois la doc technique de SPIP et des ses plugins.

Documentation des APIs de SPIP

Oui, c'est le cas, comme j'ai dit dans l'autre réponse le privé donne accès à toutes les fonctions publiques ou privées.

Documentation des APIs de SPIP

Non, ce n'est pas au même niveau tu as raison. On peut le faire dans les deux cas puisque l'info est dans le phpdoc. C'est simplement que j'ai relaté les expérimentations telles qu'elles ont été définies.

D'ailleurs autant Autodoc que APIS importent l'ensemble des fonctions publiques ou pas. Dans le cas d'APIS c'est le squelette APIS Squelettes qui n'offre que l'interface publique et tout ça pourrait être configurable d'ailleurs. Dans le privé on voit tout et on peut tout modifier.

Quant à choisir l'un ou l'autre, Matthieu a aussi émis l'idée que Autodoc pourrait finalement ne plus rien insérer en base (ce ne serait plus un plugin SPIP donc) mais devenir un template HTML en TWIG par exemple qui se sert directement des scripts générés par PHPDocumentor. Ca permettrait de na pas avoir deux plugins SPIP qui doublonnent et un site rapidement disponible le temps que APIS soit opérationnel. Mais c'est à décider.

Documentation des APIs de SPIP

Cela me semble très bon.

Réinjecter la documentation dans le code de SPIP me semble une mauvaise idée : je vois mal comment on peut avoir une documentation de base la plus complète possible qui rentre dans les commentaires du code (que moins de monde regarde).
En cela le site de PHP (et son code) fait bien le distingo entre le code, une documentation officielle, et des commentaires (qui constituent parfois les éléments les plus intéressants d'une page)

Au passage ce type de site n'a d'intérêt à mon avis que s'il peut être utilisé par les plugins (un peu comme pour le mécanisme de traduction actuel) == indispensable actuellement pour reprendre l'API de gestion des documents etc.

Excellente approche en tout cas !

Documentation des APIs de SPIP

Sinon, pour le nommage des choses, il faudra plutôt dire « code.spip.net » si le site contient toute les fonctions. Et si (par malheur) on garde une séparation, ça sera quand même « code.spip.net » pour le site qui contiendra l'ensemble, et « apis.spip.net » pour les APIs seules. « doc.spip.net » est trop générique et est donc confus.

Documentation des APIs de SPIP

Car pour ce qui est des fonctionnalités, les fonctions non-publiques aussi ont besoin d'être documentées et on besoin d'être visible : ça permet que d'autres gens apprennent et comprennent le compilateur par exemple (là ça se compte sur les doigts d'UNE main, les gens qui savent). Et donc faut pas juste que ça soit visible sur une page, mais aussi, tout comme les APIs publiques, que les gens puissent aider à écrire la documentation dans une interface facile. Cette fonctionnalité est toute aussi pertinente pour les fonctions privées.

La grande différence n'est donc pas le mécanisme, mais l'ergonomie de l'interface web qui les présentera aux gens. Et là je suis entièrement d'accord avec Éric que seules les APIs publiques doivent être mis en avant et visibles au premier abord.

Documentation des APIs de SPIP

Le fait de montrer ce qui est public ou pas, n'est pas propre au mécanisme choisi pour extraire la doc (autodoc ou apis).

Donc à mon avis, il ne faut maintenir qu'un seul logiciel permettant d'extraire et de synchroniser la documentation technique entre le code et une base. C'est bien de tester plusieurs approches, mais une fois ces tests faits, je trouve plus logique ne ne maintenir ensemble qu'un moyen commun.

Le site peut très bien n'afficher que les APIs publiques par défaut, mais laisser la possibilité en plus d'afficher les autres fonctions. De toute façon les gens pourront les trouver dans Autodoc si on laisse la séparation, donc c'est pas comme si le but était de les masquer à jamais, et que personne ne les voit à part les 10 pleupleus qui fouilleront le code complet. Dans tous les cas, on pourra trouver ces fonctions non-publiques quelques part, donc autant que tout soit avec le même outil et les mêmes facilitées.

Documentation des APIs de SPIP

Pour le « on fait quoi » je dirais pour l'autodoc :

s'il n'y a pas de forum sur autodoc, y a t'il un intérêt à ce que ce soit mis en bdd ? je ne le pense pas, à part pour la recherche dans la doc, le renommage de fonctions… mais bon, autant ne pas se prendre la tête. Mais ça veut dire utiliser les outils prévus par PHPDocumentor pour générer le site de doc (xsl ou twig) sachant que twig c'est joli à écrire, que xsl je capte rien, mais que twig, y a pas encore d'exemple d'utilisation à ce jour.
si l'autodoc est pure HTML, ça permet d'en faire un zip pour une lecture locale
mais pure HTML (sans SPIP) ça veut aussi dire se priver de pagination (et d'ajax).