Ajout des commentaires dans le code

app/Models/MotifModel.php

@@ -6,8 +6,27 @@ namespace App\Models;
 
 use App\Core\MotifCategories;
 
+/**
+ * Référentiel des motifs de créneau (`motif_planning`).
+ *
+ * Le motif porte le drapeau `compte_dans_quota`, qui décide si le temps saisi
+ * s'impute ou non sur le quota annuel de l'agent. C'est le seul point de
+ * bascule : CONGE, AUTRE_ABSENCE et JNT ne comptent pas (voir
+ * QuotaModel::REFERENCE_MINUTES pour le pourquoi).
+ *
+ * Les motifs sont classés fonctionnellement par App\Core\MotifCategories, qui
+ * distingue travail effectif, formation, congé et absence.
+ */
 final class MotifModel extends BaseModel
 {
+    /**
+     * Tous les motifs actifs, dans l'ordre d'affichage du référentiel.
+     *
+     * Liste NON filtrée par agent : voir allActiveForAgent() pour la variante
+     * qui applique les droits.
+     *
+     * @return array<int, array<string, mixed>>
+     */
     public function allActive(): array
     {
         return $this->pdo->query(
@@ -18,6 +37,11 @@ final class MotifModel extends BaseModel
         )->fetchAll();
     }
 
+    /**
+     * Identifiants des motifs actifs.
+     *
+     * @return int[]
+     */
     public function activeIds(): array
     {
         return array_map(
@@ -29,6 +53,14 @@ final class MotifModel extends BaseModel
     /**
      * Motifs réellement affectables à un agent : « Formation » disparaît de la
      * liste dès lors que l'agent n'a pas droit à l'enveloppe de formation.
+     *
+     * C'est la liste de référence des contrôles de saisie : tout motif absent
+     * d'ici est refusé côté serveur, quelle que soit l'interface utilisée.
+     *
+     * @param array<string, mixed> $agent Fiche agent (doit porter
+     *                                    droit_enveloppe_formation).
+     *
+     * @return array<int, array<string, mixed>>
      */
     public function allActiveForAgent(array $agent): array
     {