Ajout des commentaires dans le code

assets/js/structure-overview.js

@@ -1,3 +1,17 @@
+/**
+ * Planning par lieu (`PTA.modules.structureOverview`), écran structures.php.
+ *
+ * Vue EN LECTURE SEULE : aucun créneau n'est modifiable ici, la saisie se fait
+ * dans planning.php. C'est la vue complémentaire de la vue par agent — ici on
+ * regarde qui est présent sur un lieu, là où va un agent.
+ *
+ * La liste d'agents ne se limite pas aux agents rattachés au lieu : elle inclut
+ * ceux qui y sont ponctuellement planifiés, un agent pouvant travailler sur
+ * plusieurs lieux la même semaine.
+ *
+ * Un rapport de couverture est intégré à la page : il évite d'avoir à ouvrir
+ * l'écran dédié pour vérifier qu'un lieu est correctement pourvu.
+ */
 (() => {
     'use strict';
 
@@ -8,6 +22,11 @@
     const { escapeHtml, readJsonResponse, apiErrorMessage, parseIsoWeek, formatDate } = PTA.utils;
     const typeLabel = (type) => type === 'EXTRASCOLAIRE' ? 'Extrascolaire' : 'Périscolaire';
 
+    /**
+     * Balisage d'un créneau : horaires, motif, et la mention « Brouillon » si le
+     * planning n'est pas validé — la présence n'est alors pas garantie.
+     * `motif_code` alimente un nom de classe CSS et passe donc par escapeHtml().
+     */
     function entryBadge(entry) {
         return `
             <div class="overview-entry motif-${escapeHtml(String(entry.motif_code || 'autre').toLowerCase())}">
@@ -18,6 +37,11 @@
         `;
     }
 
+    /**
+     * Bandeau de couverture, en trois états : lieu NON CONFIGURÉ (aucune règle,
+     * donc aucun contrôle possible), couverture complète, ou liste des manques.
+     * La liste est plafonnée à huit plages, le reste étant dénombré.
+     */
     function coveragePanel(coverage) {
         if (!coverage?.configured) {
             return `
@@ -47,6 +71,7 @@
             </div>`;
     }
 
+    /** Rend le tableau agents × jours de la semaine, plus le bandeau de couverture. */
     function render(data) {
         const container = document.querySelector('#structure-overview-content');
         const empty = document.querySelector('#structure-overview-empty');
@@ -118,6 +143,7 @@
         `;
     }
 
+    /** Le PDF du lieu exige un lieu ET une semaine. */
     function updatePdfButton() {
         if (!openStructurePdfButton) return;
         const structureId = document.querySelector('#overview-structure')?.value;
@@ -125,6 +151,7 @@
         openStructurePdfButton.disabled = !(structureId && week);
     }
 
+    /** Ouvre le PDF du lieu dans un nouvel onglet (`noopener` par principe). */
     function openPdf() {
         const structureId = document.querySelector('#overview-structure')?.value;
         const week = document.querySelector('#overview-week')?.value;
@@ -134,6 +161,7 @@
         window.open(`api/structure_planning_pdf.php?${params.toString()}`, '_blank', 'noopener');
     }
 
+    /** Charge et rend la semaine du lieu sélectionné. */
     async function load() {
         const structureId = document.querySelector('#overview-structure')?.value;
         const week = document.querySelector('#overview-week')?.value;