Modifications docstrings de certains Contrats

capytale/contracts/src/mode.ts

@@ -1,5 +1,15 @@
 /**
  * Ce module définit la transmission du mode de l'activité.
+ *
+ * Les modes peuvent être :
+ *    - `"create"` - Pour un enseignant en train de créer/modifier une activité.
+ *    - `"assignment"` - Pour un élève/participant en train d'effectuer le travail demandé.
+ *    - `"review"` - Pour un enseignant regardant la copie d'un élève.participant (que la
+ *                   copie soit finalisée ou non: voir le contrat `workflow`).
+ *    - `"view"` - Pour un enseignant regardant une activité créée par un autre enseignant
+ *                 depuis la bibliothèque d'activité de Capytale.
+ *
+ * Souscription avec `mode:{v}`, où `{v}` est le numéro de version du contrat.
  */
 
 type Mode =
@@ -28,13 +38,14 @@ export type ModeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour indiquer le mode à l'*Application*.
-         * Ne devrait être appelé qu'une seule fois.
+         * Le *MetaPlayer* appelle systématiquement cette méthode pour indiquer le mode à l'*Application*
+         * avant d'avoir appelé la méthode `loadContent` des contrats `simple-content`.
          * 
-         * @param mode le mode à appliquer. 
+         * @param mode le mode utilisé actuellement pour l'activité. 
         */
         setMode(mode: Mode): void;
     };

capytale/contracts/src/reload.ts

@@ -1,5 +1,14 @@
 /**
- * Ce module définit le mécanisme de rechargement de l'iFrame.
+ * Ce module définit le mécanisme de rechargement de l'iFrame:
+ * 
+ * Si l'*Application* n'est pas une SWA (Single Web App), il peut lui être nécessaire de changer de page
+ * en cours d'utilisation. Dans ce cas, le *MetaPlayer* doit être notifié pour que l'iFrame soit détruite 
+ * et reconstruite avec la nouvelle URL.
+ * Ce contrat permet également de transmettre les informations sur le contenu actuel de l'*Application*
+ * entre la page initiale et la nouvelle page, sans passer par le mécanisme de sauvegarde des contrats
+ * de type `simple-content`.
+ *
+ * Souscription au contrat avec `reload:{v}`, où `{v}` est le numéro de version.
  */
 
 /**
@@ -13,25 +22,39 @@ export type ReloadV1 = {
      */
     metaplayer: {
         /**
-         * L'*Application* peut appeler cette méthode pour demander un rechargement.
-         * L'iFrame est détruite puis recréée.
+         * L'*Application* peut appeler cette méthode pour demander un rechargement avec l'url
+         * passée en argument.
+         * 
+         * - L'iFrame est détruite puis recréée avec la nouvelle adresse.
+         * - Le *MetaPlayer* récupère un état (`state`) contenant toutes les données qui devront
+         *   être ensuite passées à la nouvelle instance de l'*Application* (à minima, toutes les 
+         *   données liée à l'activité en cours).
+         * - Après chargement de la nouvelle page, l'*Application* souscrit aux différents contrats,
+         * mais le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent` : c'est la la méthode 
+         * `reloaded` du présent contrat qui sera appelée à la place.
          * 
          * @param url l'URL à charger dans l'iFrame.
-         *            Si null, l'URL actuelle est rechargée.
+         *        Si `null`, l'URL actuelle est rechargée.
+         *        ATTENTION: si la logique de l'*Application* repose sur des paramètres passés 
+         *        via l'URL, ne pas oublier de les rajouter à cet argument.
          * 
-         * @param state un état éventuel à transmettre à l'application après le rechargement.
+         * @param state un état à transmettre à l'application après le rechargement.
+         *        L'objet `state` doit être serializable avec JSON.stringify.
          * 
          */
         reload(url?: string | null, state?: any): void;
     };
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**
          * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* qu'un
-         * rechargement a eu lieu.
+         * rechargement a eu lieu et lui passé le dernier état de l'*Ap^plication*.
+         * Cette méthode est appelée en lieu et place de `loadContent`, suite à une
+         * demande de rechargement.
          * 
          * @param state l'état que l'application a transmis lors de l'appel à `reload`.
          */

capytale/contracts/src/simple-content-eval.ts

@@ -11,6 +11,11 @@ type StringEvaluation = {
     score: string;
 }
 
+
+/**Représente l'évaluation d'un exercice de l'activité.
+ *   - `evalLabel`: utiliser `"Exercice N" (sert d'identifiant pour enregistrer les données)
+ *   - `evalTitle`: titre (optionnel) de l'exercice.
+ */
 type Evaluation = {
     evalLabel: string;
     evalTitle?: string;
@@ -35,29 +40,37 @@ export type SimpleContentEvalV1<T> = {
      */
     metaplayer: {
         /**
-         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu a été modifié par l'utilisateur.
+         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu 
+         * a été modifié par l'utilisateur (permettant par exemple d'activer le bouton de sauvegarde 
+         * dans le bandeau supérieur de Capytale).
          */
         contentChanged(): void;
     };
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre
+         * les données de l'activité à l'*Application*.
          * 
-         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par défaut initiale.
+         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par 
+         * défaut initiale.
          * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption.
          * 
          * @param content le contenu de l'activité
         */
         loadContent(content: T | null): void;
 
         /**
-         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application* dans le mode create.
+         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, 
+         * dans le mode create.
+         * 
+         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
+         * initiale.
          * 
-         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut initiale.
          * 
          * @returns le contenu de l'activité
          */

capytale/contracts/src/simple-content.ts

@@ -1,10 +1,21 @@
 /**
- * Ce module définit le contrat d'échange des contenus.
+ * Ce module définit le contrat d'échange des contenus de l'activité.
+ *
+ *    - Les données peuvent être `null` lorsqu'aucune donnée n'existe pour l'activité, 
+ *      côté Capytale (typiquement: au moment de la création de l'activité).
+ *    - Les données pour une acivité doivent toujours être du même type, quel que soit 
+ *      le mode utilisé (create, assignment, ...).
+ *
+ * Souscription avec `"simple-content({type}):{v}"`, où :
+ *    - `{v}` est le numéro de version du contrat.
+ *    - `{type}` est le type de données utilisées par l'*Application*. Peut être:
+ *            json
+ *            text
  */
 
 /**
  * Un contrat pour gérer un contenu simple :
- * - un seul contenu de type `T`
+ * - un seul contenu de type `T|null`
  * - le mode assignment est le même que le mode create c'est à dire que
  *   le contenu initial pour l'élève est celui qui a été préparé par l'enseignant.
  * 
@@ -18,36 +29,52 @@ export type SimpleContentV1<T> = {
      */
     metaplayer: {
         /**
-         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu a été modifié par l'utilisateur.
+         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu 
+         * a été modifié par l'utilisateur (permettant par exemple d'activer le bouton de sauvegarde 
+         * dans le bandeau supérieur de Capytale).
          */
         contentChanged(): void;
     };
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre
+         * les données de l'activité à l'*Application*.
          * 
-         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par défaut initiale.
-         * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption.
+         *     - Si `content` est `null`, l'*Application* doit initialiser son contenu à la valeur 
+         *       par défaut initiale.
+         *     - Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une 
+         *       exeption.
          * 
          * @param content le contenu de l'activité
         */
         loadContent(content: T | null): void;
 
         /**
-         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, 
+         * lorsque l'utilisateur effectue une action demandant d'enregistrer des données sur 
+         * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur).
          * 
-         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut initiale.
+         * L'*Application* peut renvoyer `null` si le contenu correspond à la valeur par défaut
+         * initiale.
          * 
          * @returns le contenu de l'activité
          */
         getContent(): T | null;
 
         /**
-         * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu a été sauvegardé.
+         * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu 
+         * a été sauvegardé, côté Capytale.
+         *
+         * Cette notification peut être utile à l'*Application* si elle gère des états `dirty` 
+         * (données non enregistrées dans Capytale) pour éviter que l'utilisateur ne puisse faire 
+         * certaines actions qui lui ferait perdre ces données par mégarde.
+         *
+         * Cette méthode n'est appelée que si la sauvegarde a été un succès.
          */
         contentSaved(): void;
     };

capytale/contracts/src/theme.ts

@@ -1,5 +1,5 @@
 /**
- * Ce module définit la transmission du thème d'affichage.
+ * Ce module définit la transmission du thème d'affichage (`"dark"|"light"`).
  */
 
 /**
@@ -23,6 +23,7 @@ export type ThemeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

capytale/contracts/src/workflow.ts

@@ -1,5 +1,15 @@
 /**
- * Ce module définit la transmission du workflow de l'assignment.
+ * Ce module définit la transmission de l'état actuel du workflow de la copie d'un 
+ * élève/participant.
+ * L'état workflow peut prendre l'une des valeurs suivantes :
+ * 
+ *    - `"current"`  - L'élève n'a pas encore rendu la copie.
+ *    - `"finished"` - L'élève a rendu la copie : il ne peut plus la modifier (il peut encore
+ *                     la consulter ou pas, selon le réglage du "mode d'accès" de l'activité,
+ *                     dans les paramètres de l'activité).
+ *    - `"corrected"` - L'enseignant a marqué la copie comme corrigée/évaluée.
+ * 
+ * Souscription avec `workflow:{v}`, où `{v}` est le numéro de version du contrat.
  */
 
 type Workflow = 'current' | 'finished' | 'corrected';
@@ -24,13 +34,16 @@ export type WorkflowV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**
          * Le *MetaPlayer* appelle cette méthode pour indiquer le workflow à l'*Application*.
-         * Peut être appelé plusieurs fois.
+         * Cette méthode est appelée une première fois juste après un appel à `setMode` (si le contrat 
+         * `mode` a été souscrit) pour indiqué l'état initial, puis elle est rappelée à chaque fois que 
+         * l'état de la copie de l'élève/du participant est modifié.
          * 
-         * @param mode le mode à appliquer. 
+         * @param workflow: la nouvelle valeur du workflow à appliquer. 
         */
         setWorkflow(wf: Workflow): void;
     };