Modifications docstrings de certains Contrats

[FredZinelli]

Voici des suggestions de docstrings.

• - Modifié - Il y a sans doute des choses erronées, car j'y suis parfois allé au feeling, pour déduire ce qu'il se passe ou non. En particulier: reload et getContent.

• - Modifié - Pour reload, justement : je me suis rendu compte en rédigeant ma suggestion qu'il y a potentiellement des différences à discuter selon que l'Application est une SWA ou non. C'est en particulier le fait que vous parliez d'un "éventuel" état à passer à reload, qui m'a fait m'interroger à ce sujet : du côté de CodEx, si j'ai bien compris, ce n'est pas du tout éventuel mais indispensable puisqu'on change carrément de page.

• - "validé" (qui ne dit mot consent ;) ) - J'ai parfois parlé de loadContent dans des contrats qui n'ont rien à voir. Ce n'est peut-être pas désirable (ou bien à reformuler en précisant "si le contrat est implanté" ?).

• - Modifié - getContent (x2) : J'ai ajouté une info sur une contrainte de non modification des contenus durant la sauvegarde, côté Application. Il me semble en effet me souvenir de qqc à ce sujet... (et aussi parce que sinon, je ne voyais pas le but de contentSaved, donc "je me suis dit que ..."). Mais c'est vraiment au feeling.

---

Remarque :

À propos de contentSaved(), est-ce que ce ne serait pas intéressant d'y ajouter un argument booléen, pour indiquer à l'Application si la sauvegrade est un succès ou pas ? Vous avez déjà certainement du feedback dans la page elle-même, mais peut-être que l'Application pourrait un jour vouloir faire qqc de l'info ?

[tjaisson]

Je viens de revoir un truc qui m'avait interpelé et dont j'avais oublié de parler.

PoursetMode, il y a cette phrase : Ne devrait être appelé qu'une seule fois. Je ne la comprends pas franchement : si j'ai bien le contexte en tête, c'est le metaplayer qui va faire l'appel à cette méthode automatiquement. Du coup, l'utilisateur n'a pas la main sur cet aspect des choses. Est-ce que c'est une contrainte à respecter de votre côté ? À reformuler en ne sera appelée qu'une seule fois par le metaplayer ? (avec le contexte du reload, il faudrait en dire un peu plus sur le "à quel moment", je pense. C'est peut-être plutôt ne sera appelée qu'après l'appel à loadContent ?).

Je me rends compte que j'ai rédigé les docstrings en expliquant ce que font les méthodes sans adopter particulièrement le point de vue de l'application. C'est probablement une erreur car c'est bien les développeurs d'applications qui en sont les premiers destinataires. Tu dis même que ce sont les utilisateurs.
Effectivement, la phrase Ne devrait être appelé qu'une seule fois. n'est pas vraiment utile pour eux.
Concernant l'ordre des appels, il me semble qu'au moment de recevoir le contenu, l'application a probablement besoin de déjà connaitre le mode. Donc en réalité, c'est setMode qui est appelée en premier.

[tjaisson]

Je suis en train de faire mes premiers essais.

• Il faudrait aussi préciser dans les contrats que les fonctions côté application sont async (je suppose qu'elles le sont toutes) / Edit: je ne comprends plus. Ici, les fonctions ne sont pas appelées avec un await devant => ?? (il est à un niveau d'appel supérieur ?)

Techniquement, les appels distants ne peuvent qu'être asynchrones. C'est indiqué dans le readme global.

• le fournisseur d'une méthode de contrat (que ce soit le metaplayer ou l'application) peux très bien renvoyer la valeur de retour directement ou alors la renvoyer sous la forme d'une promesse (selon ce qui est le plus adapté pour lui).
• mais, de l'autre côté, le consommateur recevra toujours la valeur de retour sous la forme d'une promesse.

Ces points ne sont pas rappelés dans la rédaction des contrats car, d'une certaine façon, c'est implicite. Les contrats sont rédigés sans promesse ce qui permet d'avoir la même écriture que l'on soit fournisseur ou consommateur.

Et typescript permet d'ajouter les promesses nécessaires à partir des contrats rédigés ainsi (code).

Ne mettre ces infos que dans le readme global n'est probablement pas suffisant. Il faudrait l'ajouter par exemple dans cet autre readme. Ou alors en haut de chaque fichier de contrat.

• Qu'en est-il des appels de fonctions du côté du meta-player ? (Je n'ai pas vu de await dans la démo, mais ça ne veut pas dire qu'ils ne le sont pas. Du coup...?)

Les appels côté meta-player reçoivent aussi une réponse asynchrone. Si je n'ai pas mis d'await, c'est que ce n'était pas forcément nécessaire ou alors que c'est fait à un niveau supérieur.

• Il me semblait que tu m'avais dit que si les méthodes n'étaient pas implantées dans les objects/contrats de l'Application, les appels n'étaient pas effectués par le meta-player. Mais je viens d'avoir une erreur en souscrivant à mode:1 avec un objet vide en guise d'implantation (je n'ai pas testé si c'est pareil avec les autres contrats).

Ce qui est optionnel, c'est d'adhérer ou non à un contrat (si l'application n'en a pas besoin). Mais si le choix est fait d'adhérer, alors il faut implémenter toutes les méthodes prévues. C'est le sens que je donne au mot contrat.

• À cause de la possibilité du reload, il faudra aussi ajouter une info comme quoi ce sont les fonctions de la souscription après rechargement de la page qui seront effectivement utilisées. À posteriori c'est logique, mais j'ai dû tester pour en être sûr, vu que je ne maîtrise pas l'architecture complète et l'articulation entre la page sur capytale et l'iframe. (J'utilise des méthodes "bindées", du coup j'avais besoin d'être sûr que ce sont bien celles de la souscription après "reload" qui sont utilisées)

Je ne suis pas sûr de comprendre. Le processus de reload détruit complètement l'environnement javascript de l'iframe. Il ne serait pas possible d'appeler les fonctions d'avant rechargement car elles n'ont plus d'existence.

[FredZinelli]

• J'ai mis à jour les différents contrats en ajoutant plus d'infos sur leur but, et en rajoutant les syntaxes de souscription (pour les simple-content, c'est nécessaire, du coup, j'ai mis l'info partout)

• Je n'ai pas touché (ou presque) au contrat simple-content-eval. Ne sachant pas exactement comment/dans quelle situation il est utilisé, j'ai préféré m'abstenir. Mais il faudrait ajouter les infos équivalentes à celles dans simple-content, et expliquer dans quels cas on préfère l'un à l'autre.

• Dans contentSaved, j'ai ajouté des infos qu'il faudra que vous validiez (j'y suis encore allé au feeling... x) )

• J'ai rajouté l'info pour tous les objets application: {...} comme quoi les implantations sont asynchrones.

[FredZinelli]

Il faudra que vous ajoutiez les différents types possibles, ici.
Pareil pour le contrat simple-content-eval.

[FredZinelli]

À valider

[FredZinelli]

Je vais tâcher de clarifier mes interrogations concernant ce qui est async ou pas et pour mes histoires de contexte/binding avec les fonctions fournies lors des souscriptions aux contrats vs le reload.

Le fond du problème est que je ne sais pas comment tout ça tourne sous le capot, donc j'ai plein d'idées/questions qui me viennent (souvent "à la c...", potentiellement 😅 ).

Pour tout ce qui tourne autour du async, mes questions se résument en fait à savoir si côté application on peut faire des plans sur la comète concernant les ordres d'exécution. À la réflexion, vu que les contrats ont tout de même un côté "atomique" marqué, ça tient sans doute plus de la lubie que du questionnemnt utile.

Pour mes histoires de binding vs reload, c'est un peu la même problématique (de ne pas savoir ce qui est fait côté metaplyer). De mon point de vue je me posais en gros la question suivante. En partant de la séquence d'évènements suivante :

1. 1er chargement, donc premier socket.plug
2. reload(nouvelleUrl, ...)
3. Au chargement de la nouvelle page (point de vue Application), nouveau socket.plug de l'application

À ce stade, j'envisageais le metaplayer comme une entité persistante, hors iframe. Du coup, même après destruction de l'iframe, ne sachant pas ce que vous faites de votre côté, les fonctions passées initialement lors de la première souscription au contrat auraient pû rester stockées par le metaplayer.
La question, un peu "naïve" je l'avoue, était d'être sûr que ce serait les nouvelles fonctions de la seconde souscription qui allaient être utilisées et pas celles de la première.
En gros, au final, l'ambiguïté était pour moi que je n'étais pas certain de ce qu'il se passait concernant l'opération socket.plug après un reload.