Ajout du pdf du guide de conception.

PHPDoc.
Passage du statut en test.

base/territoires.php

@@ -2,13 +2,7 @@
 /**
  * Déclarations relatives à la base de données.
  *
- * @plugin     Territoires
- *
- * @copyright  2020
- * @author     Eric Lupinacci
- * @licence    GNU/GPL
- *
- * @package    SPIP\Territoires\Pipelines
+ * @package SPIP\TERRITOIRES\INSTALLATION
  */
 if (!defined('_ECRIRE_INC_VERSION')) {
 	return;

inc/territoires_services.php

@@ -14,7 +14,7 @@ if (!defined('_ECRIRE_INC_VERSION')) {
  * Les sous-ensembles valides sont :
  * - les régions du monde
  * - les pays
- * - les subdivisions d'un pays.
+ * - les subdivisions ou infra-subdivisions d'un pays.
  *
  * @api
  *

inc/territoires_utils.php

@@ -15,8 +15,8 @@ if (!defined('_TERRITOIRE_URL_BASE_ISOCODE')) {
 
 
 /**
- * Initialise la configuration des différents types de territoire, soit les régions du monde, les pays et
- * les subdivisions.
+ * Initialise la configuration 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
@@ -115,7 +115,7 @@ function territoires_configurer() {
 
 /**
  * Acquiert les données de territoires disponibles dans Nomenclatures.
- * La fonction utilise l'API fonctionnelle de Nomenclatures mais pourra ensuite utiliser directement API REST.
+ * La fonction utilise l'API REST de Nomenclatures.
  *
  * @internal
  *
@@ -175,7 +175,7 @@ function territoires_acquerir($type, $pays = '', $options = array()) {
 
 /**
  * Extrait, pour un les régions, les pays ou les subdivisions d'un pays, la liste des territoires ayant fait l'objet
- * d'une modification manuelle (descriptif ou logo) et la liste associations vers ses mêmes territoires.
+ * d'une modification manuelle (descriptif) et la liste associations vers ses mêmes territoires.
  * Les extras ne sont pas sauvegardés car il ne sont ni modifiables ni indexés par un id mais par un code invariant.
  *
  * @internal
@@ -333,6 +333,9 @@ function traduction_fusionner($multi_prioritaire, $multi_non_prioritaire) {
 }
 
 /**
+ * Initialise les champs de l'objet territoire à partir d'un élément reçu de l'API REST et en utilisant la configuration
+ * du type concerné et complète avec le type, le nom d'usage, le descriptif et le parent.
+ *
  * @param array  $territoire
  * @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.
@@ -375,13 +378,13 @@ function enregistrement_initialiser($territoire, $type, $pays = '') {
 		// La région d'appartenance est toujours inclus dans le champ code_num_region fourni par Nomenclatures
 		$enregistrement['iso_parent'] = $territoire['code_num_region'];
 	}
-	// TODO : comment gérer les infra subdivisions
 
 	return $enregistrement;
 }
 
 /**
- * Compile...
+ * Compile, en fonction du mode de récupération (extra avec les données de territoire ou à part), les données
+ * extra à insérer dans la table `spip_territoires_extras`.
  *
  * @internal
  *
@@ -389,8 +392,8 @@ function enregistrement_initialiser($territoire, $type, $pays = '') {
  * @param array  $types_extras
  * @param array  $source
  * @param array  $configuration
- * @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 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  $meta_extras
  *
  * @return array
@@ -450,13 +453,9 @@ function extra_compiler($mode, $types_extras, $source, $configuration, $type, $p
 }
 
 /**
- * Vérifie si le couple (type, pays) est valide, à savoir, désigne bien un sous-ensemble cohérent de territoires.
- * Les sous-ensembles valides sont :
- * - les régions du monde
- * - les pays
- * - les subdivisions d'un pays.
+ * Vérifie si le type de territoire est `subdivision` ou `infra-subdivision`.
  *
- * @api
+ * @internal
  *
  * @param string $type Type de territoires. Prends les valeurs `zone`, `country`, `subdivision` ou `infrasubdivision`.
  *

paquet.xml

@@ -2,7 +2,7 @@
 	prefix="territoires"
 	categorie="divers"
 	version="1.0.0"
-	etat="dev"
+	etat="test"
 	compatibilite="[3.3.0-dev;3.3.*]"
 	logo="territoires_logo-xx.svg"
 	documentation=""

territoires_administrations.php

@@ -2,11 +2,7 @@
 /**
  * Fichier gérant l'installation et désinstallation du plugin Territoires
  *
- * @plugin     Territoires
- * @copyright  2020
- * @author     Eric Lupinacci
- * @licence    GNU/GPL
- * @package    SPIP\Territoires\Installation
+ * @package    SPIP\TERRITOIRES\INSTALLATION
  */
 
 if (!defined('_ECRIRE_INC_VERSION')) {

territoires_fonctions.php

@@ -1,8 +1,9 @@
 <?php
 /**
  * Ce fichier contient les fonctions d'API du plugin Territoires utilisées comme filtre dans les squelettes.
- * Les autres fonctions de l'API sont dans le fichier `inc/territoire`.
+ * Les autres fonctions de l'API sont dans les fichiers `inc/territoire` et `inc/territoires_services`.
  *
+ * @package SPIP\TERRITOIRE\API
  */
 if (!defined('_ECRIRE_INC_VERSION')) {
 	return;
@@ -12,16 +13,14 @@ if (!defined('_ECRIRE_INC_VERSION')) {
 /**
  * Fournit l'ascendance géographique d'un territoire, par consultation dans la base de données.
  *
- * @param string $iso_territoire Code ISO principal du territoire
- * @param string|null $iso_parent Code ISO principal du parent direct du territoire concerné ou chaine vide sinon
- * @param string $ordre Classement de la liste : `descendant`(défaut) ou `ascendant`.
- *
- * @return array Liste des territoires ascendants.
- * @package SPIP\TERRITOIRE\API
- *
  * @api
  * @filtre
  *
+ * @param string      $iso_territoire Code ISO principal du territoire
+ * @param string|null $iso_parent     Code ISO principal du parent direct du territoire concerné ou chaine vide sinon
+ * @param string      $ordre          Classement de la liste : `descendant`(défaut) ou `ascendant`.
+ *
+ * @return array Liste des territoires ascendants.
  */
 function territoire_informer_ascendance($iso_territoire, $iso_parent = null, $ordre = 'descendant') {
 

territoires_pipelines.php

@@ -2,10 +2,6 @@
 /**
  * Utilisations de pipelines par Territoires
  *
- * @plugin     Territoires
- * @copyright  2020
- * @author     Eric Lupinacci
- * @licence    GNU/GPL
  * @package    SPIP\TERRITOIRES\PIPELINES
  */
 
@@ -18,9 +14,10 @@ if (!defined('_ECRIRE_INC_VERSION')) {
  * Territoires ajoute les éventuels caractéristiques complémentaires et le formulaire d'association.
  *
  * @pipeline affiche_milieu
+ *
  * @param  array $flux Données du pipeline
  *
- * @return array Données du pipeline
+ * @return array Données du pipeline modifiées pour refléter le traitement.
  */
 function territoires_affiche_milieu($flux) {
 
@@ -91,7 +88,7 @@ function territoires_affiche_milieu($flux) {
  *
  * @param  array $flux Données du pipeline
  *
- * @return array Données du pipeline
+ * @return array Données du pipeline modifiées pour refléter le traitement.
  */
 function territoires_affiche_gauche($flux) {
 
@@ -140,9 +137,9 @@ function territoires_affiche_gauche($flux) {
  * Enlever l'id_territoire de la liste des critères conditionnels pour la table `spip_territoires`
  * car cela peut renvoyer une liste vide si l'env contient déjà l'id du territoire.
  *
- * @param array $flux
+ * @param array $flux Données du pipeline
  *
- * @return array
+ * @return array Données du pipeline modifiées pour refléter le traitement.
  */
 function territoires_exclure_id_conditionnel($flux) {
 	if ($flux['args']['table'] == 'spip_territoires') {
@@ -185,13 +182,13 @@ function territoires_pre_edition($flux) {
 
 /**
  * Optimiser la base de données
- *
  * Supprime les liens orphelins de l'objet vers quelqu'un et de quelqu'un vers l'objet.
  *
  * @pipeline optimiser_base_disparus
+ *
  * @param  array $flux Données du pipeline
  *
- * @return array Données du pipeline
+ * @return array Données du pipeline modifiées pour refléter le traitement.
  */
 function territoires_optimiser_base_disparus($flux) {