From 933e13f9d28820990eddd70017b9a60887446d5c Mon Sep 17 00:00:00 2001
From: Matthieu Marcillaud <marcimat@rezo.net>
Date: Sat, 16 Feb 2013 15:18:21 +0000
Subject: [PATCH] Autre PHPDoc sur des balises
---
ecrire/inc/filtres.php | 78 ++++++++++++++++-----
ecrire/public/balises.php | 141 ++++++++++++++++++++++++++++++--------
2 files changed, 175 insertions(+), 44 deletions(-)
diff --git a/ecrire/inc/filtres.php b/ecrire/inc/filtres.php
index 8d5ffd0a3a..d258274e5e 100644
--- a/ecrire/inc/filtres.php
+++ b/ecrire/inc/filtres.php
@@ -1549,16 +1549,48 @@ function extraire_trads($bloc) {
return $trads;
}
-//
-// Ce filtre retourne la donnee si c'est la premiere fois qu'il la voit ;
-// possibilite de gerer differentes "familles" de donnees |unique{famille}
-# |unique{famille,1} affiche le nombre d'elements affiches (preferer toutefois #TOTAL_UNIQUE)
-# ameliorations possibles :
-# 1) si la donnee est grosse, mettre son md5 comme cle
-# 2) purger $mem quand on change de squelette (sinon bug inclusions)
-//
-// http://www.spip.net/@unique
-// http://doc.spip.org/@unique
+
+/**
+ * Retourne la donnée si c'est la première fois qu'il la voit
+ *
+ * Il est possible de gérer différentes "familles" de données avec
+ * le second paramètre.
+ *
+ * @filtre unique
+ * @link http://www.spip.net/4320
+ * @used-by balise_TOTAL_UNIQUE_dist()
+ * @example
+ * ```
+ * [(#ID_SECTEUR|unique)]
+ * [(#ID_SECTEUR|unique{tete})] n'a pas d'incidence sur
+ * [(#ID_SECTEUR|unique{pied})]
+ * [(#ID_SECTEUR|unique{pied,1})] affiche le nombre d'éléments.
+ * Préférer totefois #TOTAL_UNIQUE{pied}
+ * ```
+ *
+ * @todo
+ * Ameliorations possibles :
+ *
+ * 1) si la donnée est grosse, mettre son md5 comme clé
+ * 2) purger $mem quand on change de squelette (sinon bug inclusions)
+ *
+ * @param string $donnee
+ * Donnée que l'on souhaite unique
+ * @param string $famille
+ * Famille de stockage (1 unique donnée par famille)
+ *
+ * - _spip_raz_ : (interne) Vide la pile de mémoire et la retourne
+ * - _spip_set_ : (interne) Affecte la pile de mémoire avec la donnée
+ * @param bool $cpt
+ * True pour obtenir le nombre d'éléments différents stockés
+ * @return string|int|array|null|void
+ *
+ * - string : Donnée si c'est la première fois qu'elle est vue
+ * - void : si la donnée a déjà été vue
+ * - int : si l'on demande le nombre d'éléments
+ * - array (interne) : si on dépile
+ * - null (interne) : si on empile
+**/
function unique($donnee, $famille='', $cpt = false) {
static $mem = array();
// permettre de vider la pile et de la restaurer
@@ -2455,12 +2487,26 @@ function filtre_foreach_dist($balise_deserializee, $modele = 'foreach') {
return $texte;
}
-// renvoie la liste des plugins actifs du site
-// si le premier parametre est un prefix de cette liste, renvoie vrai, faux sinon
-// la valeur du second parametre si celui-ci renvoie a une information connue
-// cf liste_plugin_actifs() pour connaitre les informations affichables
-// appelee par la balise #PLUGIN
-// http://doc.spip.org/@filtre_info_plugin_dist
+
+/**
+ * Obtient des informations sur les plugins actifs
+ *
+ * @filtre info_plugin
+ * @used-by balise_PLUGIN_dist() Appelé par la balise #PLUGN
+ * @uses liste_plugin_actifs() Voir liste_plugin_actifs() pour connaître les informations affichables
+ *
+ * @param string $plugin
+ * Préfixe du plugin ou chaîne vide
+ * @param string $type_info
+ * Type d'info demandée
+ * @return array|string|bool
+ *
+ * - Liste sérialisée des préfixe de plugins actifs (si $plugin = '')
+ * - Suivant $type_info, avec $plugin un préfixe
+ * - est_actif : renvoie true s'il est actif, false sinon
+ * - x : retourne l'information x du plugin si présente (et plugin actif)
+ * - tout : retourne toutes les informations du plugin actif
+**/
function filtre_info_plugin_dist($plugin, $type_info) {
include_spip('inc/plugin');
$plugin = strtoupper($plugin);
diff --git a/ecrire/public/balises.php b/ecrire/public/balises.php
index 151f727978..a2eec31fb0 100644
--- a/ecrire/public/balises.php
+++ b/ecrire/public/balises.php
@@ -2018,13 +2018,25 @@ function balise_DOUBLONS_dist($p) {
}
-//
-// #PIPELINE
-// pour permettre aux plugins d'inserer des sorties de pipeline dans un squelette
-// #PIPELINE{insert_body}
-// #PIPELINE{insert_body,flux}
-//
-// http://doc.spip.org/@balise_PIPELINE_dist
+
+/**
+ * Compile la balise `#PIPELINE` pour permettre d'insérer des sorties de
+ * pipeline dans un squelette
+ *
+ * @balise PIPELINE
+ * @see pipeline()
+ * @example
+ * ```
+ * #PIPELINE{nom}
+ * #PIPELINE{nom,données}
+ * #PIPELINE{boite_infos,#ARRAY{data,'',args,#ARRAY{type,rubrique,id,#ENV{id_rubrique}}}}
+ * ```
+ *
+ * @param Champ $p
+ * Pile au niveau de la balise
+ * @return Champ
+ * Pile complétée par le code à générer
+**/
function balise_PIPELINE_dist($p) {
$_pipe = interprete_argument_balise(1,$p);
if (!$_pipe) {
@@ -2039,11 +2051,27 @@ function balise_PIPELINE_dist($p) {
return $p;
}
-//
-// #EDIT
-// une balise qui ne fait rien, pour surcharge par le plugin widgets
-//
-// http://doc.spip.org/@balise_EDIT_dist
+
+/**
+ * Compile la balise `#EDIT` qui ne fait rien dans SPIP
+ *
+ * Cette balise ne retourne rien mais permet d'indiquer, pour certains plugins
+ * qui redéfinissent cette balise, le nom du champ SQL (ou le nom d'un contrôleur)
+ * correspondant à ce qui est édité. Cela sert particulièrement au plugin Crayons.
+ * Ainsi en absence du plugin, la balise est toujours reconnue (mais n'a aucune action).
+ *
+ * @balise EDIT
+ * @link http://www.spip.net/4584
+ * @example
+ * ```
+ * [<div class="#EDIT{texte} texte">(#TEXTE)</div>]
+ * ```
+ *
+ * @param Champ $p
+ * Pile au niveau de la balise
+ * @return Champ
+ * Pile complétée par le code à générer
+**/
function balise_EDIT_dist($p) {
$p->code = "''";
$p->interdire_scripts = false;
@@ -2051,15 +2079,25 @@ function balise_EDIT_dist($p) {
}
-//
-// #TOTAL_UNIQUE
-// pour recuperer le nombre d'elements affiches par l'intermediaire du filtre
-// |unique
-// usage:
-// #TOTAL_UNIQUE afiche le nombre de #BALISE|unique
-// #TOTAL_UNIQUE{famille} afiche le nombre de #BALISE|unique{famille}
-//
-// http://doc.spip.org/@balise_TOTAL_UNIQUE_dist
+
+/**
+ * Compile la balise `#TOTAL_UNIQUE` qui récupère le nombre d'éléments
+ * différents affichés par le filtre `unique`
+ *
+ * @balise TOTAL_UNIQUE
+ * @link http://www.spip.net/4374
+ * @see unique()
+ * @example
+ * ```
+ * #TOTAL_UNIQUE affiche le nombre de #BALISE|unique
+ * #TOTAL_UNIQUE{famille} afiche le nombre de #BALISE|unique{famille}
+ * ```
+ *
+ * @param Champ $p
+ * Pile au niveau de la balise
+ * @return Champ
+ * Pile complétée par le code à générer
+**/
function balise_TOTAL_UNIQUE_dist($p) {
$_famille = interprete_argument_balise(1,$p);
$_famille = $_famille ? $_famille : "''";
@@ -2167,9 +2205,26 @@ function balise_AUTORISER_dist($p) {
return $p;
}
-// Appelle la fonction info_plugin
-// Afficher des informations sur les plugins dans le site public
-// http://doc.spip.org/@balise_PLUGIN_dist
+
+/**
+ * Compile la balise `#PLUGIN` qui permet d’afficher les informations d'un plugin actif
+ *
+ * @balise PLUGIN
+ * @see filtre_info_plugin_dist()
+ * @link http://www.spip.net/4591
+ * @example
+ * ```
+ * #PLUGIN Retourne la liste sérialisée des préfixes de plugins actifs
+ * #PLUGIN{prefixe} Renvoie true si le plugin avec ce préfixe est actif
+ * #PLUGIN{prefixe, x} Renvoie l'information x du plugin (s'il est actif)
+ * #PLUGIN{prefixe, tout} Renvoie toutes les informations du plugin (s'il est actif)
+ * ```
+ *
+ * @param Champ $p
+ * Pile au niveau de la balise
+ * @return Champ
+ * Pile complétée par le code à générer
+**/
function balise_PLUGIN_dist($p) {
$plugin = interprete_argument_balise(1,$p);
$plugin = isset($plugin) ? str_replace('\'', '"', $plugin) : '""';
@@ -2290,16 +2345,46 @@ function balise_BOUTON_ACTION_dist($p){
+/**
+ * Compile la balise `#SLOGAN_SITE_SPIP` qui retourne le slogan du site
+ *
+ * @balise SLOGAN_SITE_SPIP
+ * @example
+ * ```
+ * [<p id="slogan">(#SLOGAN_SITE_SPIP)</p>]
+ * ```
+ *
+ * @param Champ $p
+ * Pile au niveau de la balise
+ * @return Champ
+ * Pile complétée par le code à générer
+ */
function balise_SLOGAN_SITE_SPIP_dist($p) {
$p->code = "\$GLOBALS['meta']['slogan_site']";
#$p->interdire_scripts = true;
return $p;
}
-// #HTML5
-// Renvoie ' ' si le webmestre souhaite que SPIP genere du code (X)HTML5 sur
-// le site public, et '' si le code doit etre strictement compatible HTML4
-// http://doc.spip.org/@balise_HTML5_dist
+
+/**
+ * Compile la balise `#HTML5` indiquant si l'espace public peut utiliser du HTML5
+ *
+ * Renvoie `' '` si le webmestre souhaite que SPIP génère du code (X)HTML5 sur
+ * le site public, et `''` si le code doit être strictement compatible HTML4
+ *
+ * @balise HTML5
+ * @uses html5_permis()
+ * @example
+ * ```
+ * [(#HTML5) required="required"]
+ * <input[ (#HTML5|?{type="email",type="text"})] ... />
+ * ```
+ *
+ * @param Champ $p
+ * Pile au niveau de la balise
+ * @return Champ
+ * Pile complétée par le code à générer
+ */
function balise_HTML5_dist($p) {
$p->code = html5_permis() ? "' '" : "''";
$p->interdire_scripts = false;
--
GitLab