Quelques mises à jour avant un changement d'organisation.

inc/ncore_cache.php

@@ -11,8 +11,8 @@ if (!defined('_ECRIRE_INC_VERSION')) {
 
 if (!defined('_NCORE_DIRCACHE')) {
 	/**
-	 * Dossier racine dans lesquels tous les caches de N-Core seront écrits.
-	 * Les caches sont répartis suivant le service dans un sous-dossier `/${service}`.
+	 * Dossier racine dans lesquels tous les caches de N-Core seront rangés.
+	 * Les caches sont répartis suivant le plugin dans un sous-dossier `/${plugin}`.
 	 */
 	define('_NCORE_DIRCACHE', _DIR_CACHE . 'ncore/');
 }
@@ -55,25 +55,28 @@ if (!defined('_NCORE_NOMCACHE_NOISETTE_CONTEXTE')) {
 
 
 /**
- * Lit le cache spécifié pour un service donné et renvoie le contenu sous forme de tableau éventuellement
- * vide.
+ * Lit le cache spécifié pour un plugin donné et renvoie le contenu sous forme de tableau
+ * éventuellement vide.
  *
- * @param string	$service
- *      Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
- *      un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
+ * @api
+ * @uses lire_fichier_securise()
+ *
+ * @param string	$plugin
+ *      Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
+ *      ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
  * @param string	$nom_cache
  * 		Nom et extension du fichier cache.
  *
  * @return array
  * 		Contenu du fichier sous la forme d'un tableau éventuellement vide.
  */
-function cache_lire($service, $nom_cache) {
+function cache_lire($plugin, $nom_cache) {
 
 	// Initialisation du contenu du cache
 	$cache = array();
 
-	// Détermination du nom du cache en fonction du service appelant et du type
-	$fichier_cache = _NCORE_DIRCACHE . "${service}/${nom_cache}";
+	// Détermination du nom du cache en fonction du plugin appelant et du type
+	$fichier_cache = _NCORE_DIRCACHE . "${plugin}/${nom_cache}";
 
 	include_spip('inc/flock');
 	if (lire_fichier_securise($fichier_cache, $contenu)) {
@@ -85,11 +88,14 @@ function cache_lire($service, $nom_cache) {
 
 
 /**
- * Ecrit le contenu d'un tableau dans le cache spécifié pour un service donné.
+ * Ecrit le contenu d'un tableau dans le cache spécifié pour un plugin donné.
+ *
+ * @api
+ * @uses ecrire_fichier_securise()
  *
- * @param string	$service
- *      Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
- *      un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
+ * @param string	$plugin
+ *      Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
+ *      ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
  * @param string	$nom_cache
  * 		Nom et extension du fichier cache.
  * @param array     $contenu_cache
@@ -97,13 +103,13 @@ function cache_lire($service, $nom_cache) {
  *
  * @return void
  */
-function cache_ecrire($service, $nom_cache, $contenu_cache) {
+function cache_ecrire($plugin, $nom_cache, $contenu_cache) {
 
 	// Création du répertoire du cache si besoin
 	$dir_cache = sous_repertoire(_DIR_CACHE, 'ncore');
-	$dir_cache = sous_repertoire($dir_cache, $service);
+	$dir_cache = sous_repertoire($dir_cache, $plugin);
 
-	// Détermination du nom du cache en fonction du service appelant et du type
+	// Détermination du nom du cache en fonction du plugin appelant et du type
 	$fichier_cache = "${dir_cache}${nom_cache}";
 
 	// On vérifie que le contenu est bien un tableau. Si ce n'est pas le cas on le transforme en tableau.
@@ -118,20 +124,23 @@ function cache_ecrire($service, $nom_cache, $contenu_cache) {
 
 
 /**
- * Supprime le cache cache spécifié pour un service donné.
+ * Supprime le cache cache spécifié pour un plugin donné.
+ *
+ * @api
+ * @uses supprimer_fichier()
  *
- * @param string	$service
- *      Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
- *      un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
+ * @param string	$plugin
+ *      Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
+ *      ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
  * @param string	$nom_cache
  * 		Nom et extension du fichier cache.
  *
  * @return void
  */
-function cache_supprimer($service, $nom_cache) {
+function cache_supprimer($plugin, $nom_cache) {
 
-	// Détermination du nom du cache en fonction du service appelant et du type
-	$fichier_cache = _NCORE_DIRCACHE . "${service}/${nom_cache}";
+	// Détermination du nom du cache en fonction du plugin appelant et du type
+	$fichier_cache = _NCORE_DIRCACHE . "${plugin}/${nom_cache}";
 
 	// Suppression du fichier cache
 	include_spip('inc/flock');

inc/ncore_noisette.php

@@ -4,9 +4,13 @@ if (!defined('_ECRIRE_INC_VERSION')) {
 	return;
 }
 
+
 /**
- * @param       $noisette
- * @param array $options
+ * Phrase le fichier YAML d'une espece de noisette et renvoie sa description si celle-ci a changé
+ * sinon renvoie un indicateur permettant de savoir que le YAML est identique.
+ *
+ * @param string	$noisette
+ * @param array		$options
  *
  * @return array
  */

ncore/ncore.php

@@ -79,11 +79,11 @@ function ncore_noisette_lister_signatures($service) {
  * 		Cet argument n'est utilisé que si la fonction N-Core est appelée.
  * @param array		$noisettes
  * 		Tableau associatif à 3 entrées fournissant les descriptions des noisettes nouvelles, obsolètes et modifiées:
- * 		- `obsoletes` : liste des identifiants de noisette devenus obsolètes
- * 		- `modifiees` : liste des descriptions des noisettes dont le fichier YAML a été modifié
- *      - `nouvelles` : liste des descriptions de nouvelles noisettes.
- * 		Si $recharger est à `true`, seul l'index `nouvelles` est fourni dans le tableau $noisettes.
+ * 		- 'obsoletes' : liste des identifiants de noisette devenus obsolètes
+ * 		- 'modifiees' : liste des descriptions des noisettes dont le fichier YAML a été modifié
+ *      - 'nouvelles' : liste des descriptions de nouvelles noisettes.
  *
+ * 		Si $recharger est à `true`, seul l'index `nouvelles` est fourni dans le tableau $noisettes.
  * @param bool		$recharger
  *      Indique si le chargement en cours est forcé ou pas. Cela permet à la fonction N-Core ou au service
  *      concerné d'optimiser le traitement sachant que seules les noisettes nouvelles sont fournies.

ncore_fonctions.php

@@ -9,9 +9,10 @@ if (!defined('_ECRIRE_INC_VERSION')) {
 }
 
 // -------------------------------------------------------------------
-// ------------------------- API NOISETTES ---------------------------
+// ------------------------- API COMPILATION ---------------------------
 // -------------------------------------------------------------------
 
+
 /**
  * Charge ou recharge les descriptions de noisettes à partir des fichiers YAML.
  * Les noisettes sont recherchées dans un répertoire relatif fourni en argument.
@@ -20,10 +21,9 @@ if (!defined('_ECRIRE_INC_VERSION')) {
  * des fichiers YAML.
  *
  * @api
- * @filtre
  *
  * @param string	$service
- *      Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
+ *      Le service permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
  *      un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
  *      La fonction utilisera les fonctions de lecture des md5 et de stockage des descriptions de noisettes,
  * 		spécifiques au service, ou à défaut, celles fournies par N-Core.
@@ -148,7 +148,6 @@ function ncore_noisette_charger($service, $dossier = 'noisettes/', $recharger =
  * Les données textuelles peuvent subir une traitement typo si demandé.
  *
  * @api
- * @filtre
  *
  * @param string	$service
  *      Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou