Refine public documentation and code comments

app/Services/GeocodeService.php

@@ -7,7 +7,7 @@ final class GeocodeService
      * Retour: ['lat'=>float, 'lng'=>float, 'display_name'=>string] ou null
      *
      * IMPORTANT:
-     * - Respecte le fair use : pas de spam (cache côté DB chez toi, et TTL)
+     * - Limite les appels au service grâce au cache local et à son TTL
      * - User-Agent explicite
      */
     public static function geocode(string $query): ?array

app/Services/IcadService.php

@@ -38,7 +38,7 @@ final class IcadService
             return true;
         }
 
-        // si en erreur → on retente
+        // Une entrée en erreur peut être actualisée lors d'une nouvelle tentative.
         if (($cache['status'] ?? '') !== 'ok') {
             return true;
         }
@@ -227,13 +227,13 @@ final class IcadService
             return html_entity_decode($m[3], ENT_QUOTES);
         }
 
-        // 2) fallback: value avant name
+        // 2) Accepte aussi les attributs placés dans l'ordre inverse.
         $re2 = '/<input\b[^>]*\bvalue=(["\'])(.*?)\1[^>]*\bname=(["\'])' . $field . '\3[^>]*>/is';
         if (preg_match($re2, $html, $m)) {
             return html_entity_decode($m[2], ENT_QUOTES);
         }
 
-        // 3) si fieldName == _token : on prend le 1er _token trouvé
+        // 3) Utilise le premier jeton générique lorsque le champ demandé est _token.
         if ($fieldName === '_token') {
             if (preg_match('/<input\b[^>]*\bname=(["\'])_token\1[^>]*\bvalue=(["\'])(.*?)\2[^>]*>/is', $html, $m)) {
                 return html_entity_decode($m[3], ENT_QUOTES);
@@ -264,7 +264,7 @@ final class IcadService
             return $p;
         }
 
-        // fallback HTML
+        // Recherche de l'identifiant dans le HTML lorsque l'URL ne le contient pas.
         if (preg_match('~href=["\'](/animal/\d+)["\']~', $resp['body'], $m)) {
             return $m[1];
         }
@@ -336,9 +336,9 @@ final class IcadService
         // Adresse postale: i-CAD ne la met pas toujours dans un bloc unique, mais on tente
         $ownerPostal = $txt('//*[@id="down_right_block"]//*[contains(@class,"coords")]//*[contains(@class,"postal")]');
         if ($ownerPostal === '') {
-            // fallback: parfois l’adresse est dans le même bloc coords mais pas taggée
+            // L'adresse peut être présente dans le bloc de coordonnées sans libellé dédié.
             $coordsText = $txt('//*[@id="down_right_block"]//*[contains(@class,"coords")]');
-            // on évite de tout recracher, juste si on détecte des numéros/rue
+            // Ne conserve le bloc que s'il ressemble à une adresse postale.
             $ownerPostal = $coordsText;
         }