Mise au point du PHPDoc

inc/requeter_isocode.php

@@ -9,6 +9,10 @@ if (!defined('_ECRIRE_INC_VERSION')) {
 }
 
 if (!defined('_TERRITOIRE_COEFF_MAX_DISTANT')) {
+	/**
+	 * Coefficient multiplicateur de la constante SPIP `_INC_DISTANT_MAX_SIZE` permettant de calculer la taille max
+	 * d'une réponse à `recuperer_url()` si aucune taille n'est précisée dans l'appel.
+	 */
 	define('_TERRITOIRE_COEFF_MAX_DISTANT', 8);
 }
 
@@ -28,7 +32,9 @@ if (!defined('_TERRITOIRE_COEFF_MAX_DISTANT')) {
  * @param null|int $taille_max Taille maximale du flux récupéré suite à la requête.
  *                             `null` désigne la taille par défaut.
  *
- * @return array
+ * @return array Tableau de la réponse. Si l'index `erreur est présent c'est que la requête s'est mal déroulée`et
+ *               la valeur retournée est une chaine qui identifie l'erreur.
+ *               Sinon, l'index `page` du flux reçu est retourné après décodage JSON.
  */
 function inc_requeter_isocode_dist($url_base, $collection, $filtres, $taille_max = null) {
 

inc/territoire.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * API de gestion des territoires.
+ * API de gestion des objets territoire.
  *
  * @package SPIP\TERRITOIRES\API
  */
@@ -17,12 +17,13 @@ if (!defined('_ECRIRE_INC_VERSION')) {
  *
  * @param string $type    Type de territoires. Prends les valeurs `zone`, `country`, `subdivision` ou `infrasubdivision`.
  * @param string $pays    Code ISO 3166-1 alpha2 du pays si le type est `subdivision` ou `infrasubdivision` sinon une chaine vide.
- * @param array  $options Options de peuplement (défaut à `false`) :
- *                        - `force` : si `true` force le repeuplement même si le sha est identique.
+ * @param array  $options Tableau des options de peuplement:
+ *                        - `force` : si `true` force le repeuplement même si le sha est identique (`false` par défaut).
  *                        - `extras`: tableau des types d'extras à peupler soit `code` pour les codes alternatifs
  *                        et `info` pour le caractéristiques (table spip_territoires_extras)
  *
- * @return array
+ * @return array Tableau retour de la fonction permettant de connaitre le résultat du traitement (utile pour l'affichage
+ *               du message dans le formulaire de peuplement).
  */
 function territoire_peupler($type, $pays, $options = array()) {
 
@@ -240,7 +241,8 @@ function territoire_peupler($type, $pays, $options = array()) {
  * @param string $type Type de territoires. Prends les valeurs `zone`, `country`, `subdivision` ou `infrasubdivision`.
  * @param string $pays Code ISO 3166-1 alpha2 du pays si le type est `subdivision` ou `infrasubdivision` sinon une chaine vide.
  *
- * @return array Liste des code ISO 3166-1 alpha2 des pays chargés sous la forme [code] = nom multi.
+ * @return array Tableau retour de la fonction permettant de connaitre le résultat du traitement (utile pour l'affichage
+ *               du message dans le formulaire de peuplement).
  */
 function territoire_depeupler($type, $pays = '') {
 
@@ -346,7 +348,7 @@ function territoire_depeupler($type, $pays = '') {
  * @param string       $type Type de territoires. Prends les valeurs `zone`, `country`, `subdivision` ou `infrasubdivision`.
  * @param array|string $pays Code ISO 3166-1 alpha2 du pays si le type est `subdivision` ou `infrasubdivision` sinon une chaine vide.
  *
- * @return bool true si le territoire est chargé, false sinon.
+ * @return bool `true` si le territoire est chargé, `false` sinon.
  */
 function territoire_est_peuple($type, $pays = '') {
 
@@ -372,8 +374,8 @@ function territoire_est_peuple($type, $pays = '') {
 }
 
 /**
- * Teste si les informations complémentaires d’un type de territoire sont chargées en base.
- * La fonction lit la meta de chargement et non la table `spip_territoires`.
+ * Teste si les codes alternatifs ou les caractéristiques additionnelles d’un type de territoire sont chargées en base.
+ * La fonction lit la meta de chargement et non la table `spip_territoires_extras`.
  *
  * @api
  *
@@ -381,7 +383,7 @@ function territoire_est_peuple($type, $pays = '') {
  * @param string $pays       Code ISO 3166-1 alpha2 du pays si le type est `subdivision` ou `infrasubdivision` sinon une chaine vide.
  * @param string $type_extra Type d'extra. Prends les valeurs `code` ou `info`.
  *
- * @return bool true si le territoire est chargé, false sinon.
+ * @return bool `true` si le territoire est chargé, `false` sinon.
  */
 function territoire_extra_est_peuple($type, $pays, $type_extra) {
 

inc/territoires_services.php

@@ -41,13 +41,13 @@ function type_pays_est_valide($type, $pays = '') {
 
 /**
  * Compare le sha passé en argument pour le type de territoire concerné avec le sha stocké dans la meta
- * pour cette même type.
+ * pour ce même type.
  *
  * @api
  *
  * @param string $sha      SHA à comparer à celui du type de territoire.
  * @param string $meta     Nom de la meta de consignation
- * @param string $consigne Nom de la variable de consigne fonction du type et du pays éventuellement.
+ * @param string $consigne Nom de la variable de consignation, fonction du type et du pays éventuellement.
  *
  * @return bool `true` si le sha passé en argument est identique au sha stocké pour la table choisie, `false` sinon.
  */

inc/territoires_utils.php

@@ -9,19 +9,23 @@ if (!defined('_ECRIRE_INC_VERSION')) {
 }
 
 if (!defined('_TERRITOIRE_URL_BASE_ISOCODE')) {
+	/**
+	 * Endpoint de l'API REST hébergeant les données de Nomenclatures.
+	 */
 	define('_TERRITOIRE_URL_BASE_ISOCODE', 'https://contrib.spip.net/http.api/ezrest');
 }
 
 
 
 /**
- * Initialise la configuration des différents types de territoire, soit les régions du monde, les pays,
+ * Initialise la configuration de chargement des différents types de territoire, soit les régions du monde, les pays,
  * les subdivisions et infra-subdivisions.
  * Cette configuration est stockée dans la meta `territoires` à l’installation et n'est pas modifiable.
  *
  * @internal
  *
- * @return array
+ * @return array Tableau des configurations de chaque type de territoire définissant comment récupérer et interpréter
+ *               les données de Nomenclatures pour remplir les tables de territoires.
  */
 function territoires_configurer() {