Autre PHPDoc sur des balises

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);

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;