From 6f823088e3dcc2a272302480a57a5d8b1eb2f0a7 Mon Sep 17 00:00:00 2001
From: tcharlss <tcharlss@bravecassine.com>
Date: Thu, 12 Dec 2024 19:33:55 +0100
Subject: [PATCH] docs: phpdoc {lang_select}
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explication un peu plus détaillée et exemple pour lever toute ambiguïté sur ce que fait le critère.
---
 public/criteres.php | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/public/criteres.php b/public/criteres.php
index c85644feb..e9ba57a31 100644
--- a/public/criteres.php
+++ b/public/criteres.php
@@ -163,13 +163,31 @@ function critere_doublons_dist($idb, &$boucles, $crit) {
 /**
  * Compile le critère {lang_select}
  *
- * Permet de restreindre ou non une boucle en affichant uniquement
- * les éléments dans la langue en cours. Certaines boucles
- * tel que articles et rubriques restreignent par défaut sur la langue
- * en cours.
+ * Ce critère indique d'utiliser la langue de l'objet de la boucle
+ * comme langue du contexte intérieur de la boucle.
  *
- * Sans définir de valeur au critère, celui-ci utilise 'oui' comme
- * valeur par défaut.
+ * Cela revient à faire `[(#LANG|lang_select)]` en tout début de boucle.
+ *
+ * En conséquence, <multi>, <:idiome_langue:> et `_T` utiliseront la langue de l'objet
+ * au lieu de la langue du contexte global.
+ *
+ * Certaines boucles telles que articles et rubriques ont ce comportement par défaut.
+ *
+ * Le critère accepte un paramètre optionnel :
+ * - '' ou 'oui' pour activer ce comportement.
+ * - 'non' pour désactiver ce comportement.
+ *
+ * @example
+ * ```
+ * Ici #LANG est celle du contexte global, par exemple le français.
+ * <BOUCLE(ARTICLES) {lang_select} {lang=en} {0,1}>
+ * Ici les balises <multi> et cie sont en anglais, idem article.
+ * </BOUCLE>
+ * <BOUCLE(ARTICLES) {lang_select=non} {lang=en} {0,1}>
+ * Ici les balises <multi> et cie sont en français, idem contexte global.
+ * </BOUCLE>
+ * Ici #LANG est le français.
+ * ```
  *
  * @param string $idb Identifiant de la boucle
  * @param array $boucles AST du squelette
-- 
GitLab