Refine public documentation and code comments

app/Controllers/AnimalPhotoActions.php

@@ -141,7 +141,7 @@ trait AnimalPhotoActions
                 continue;
             }
 
-            // RÈGLE : jamais une privée en principale
+            // Une photo privée ne peut pas devenir la photo principale.
             $isPrimary = !$hasPrimary && $isPublic === 1 ? 1 : 0;
             if ($isPrimary === 1) {
                 $hasPrimary = true;
@@ -221,7 +221,7 @@ trait AnimalPhotoActions
             throw $e;
         }
 
-        // Historique si tu veux
+        // Conserve la suppression dans l'historique de la fiche.
         if (method_exists(__CLASS__, 'logHistory')) {
             self::logHistory($animalId, 'photo', 'Photo principale modifiée');
         }
@@ -274,7 +274,7 @@ trait AnimalPhotoActions
             @unlink($path);
         }
 
-        // Si on a supprimé la principale, on met la plus récente restante en principale
+        // Remplace une photo principale supprimée par la plus récente encore disponible.
         if ($wasPrimary) {
             $pid = $db
                 ->query('SELECT id FROM animal_photos WHERE animal_id=' . (int) $animalId . ' ORDER BY id DESC LIMIT 1')