From a1e0e732c2d49160263eb8d591edc00b85ebc9fe Mon Sep 17 00:00:00 2001
From: Matthieu Marcillaud <marcimat@rezo.net>
Date: Tue, 17 Jul 2012 19:00:18 +0000
Subject: [PATCH] =?UTF-8?q?PhpDoc=E2=80=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
ecrire/inc/filtres.php | 11 ++--
ecrire/inc/filtres_ecrire.php | 62 +++++++++++-----------
ecrire/inc/pipelines.php | 91 +++++++++++++++++++++++++++------
ecrire/inc/pipelines_ecrire.php | 7 +--
ecrire/inc/queue.php | 20 +++++---
5 files changed, 127 insertions(+), 64 deletions(-)
diff --git a/ecrire/inc/filtres.php b/ecrire/inc/filtres.php
index a301b1495c..d7970dcf24 100644
--- a/ecrire/inc/filtres.php
+++ b/ecrire/inc/filtres.php
@@ -2903,12 +2903,13 @@ function objet_icone($objet,$taille=24){
/**
* Fonction de secours pour inserer le head_css de facon conditionnelle
- * appelee en filtre sur le squelette qui contient #INSERT_HEAD
- * elle verifie l'absence eventuelle de #INSERT_HEAD_CSS et y suplee si besoin
- * pour assurer la compat avec les squelettes qui n'utilisent pas
*
- * @param string $flux
- * @return void
+ * Appelée en filtre sur le squelette qui contient #INSERT_HEAD,
+ * elle vérifie l'absence éventuelle de #INSERT_HEAD_CSS et y suplée si besoin
+ * pour assurer la compat avec les squelettes qui n'utilisent pas.
+ *
+ * @param string $flux Code HTML
+ * @return string Code HTML
*/
function insert_head_css_conditionnel($flux){
if (strpos($flux,'<!-- insert_head_css -->')===false
diff --git a/ecrire/inc/filtres_ecrire.php b/ecrire/inc/filtres_ecrire.php
index 537be053dc..178a30e3eb 100644
--- a/ecrire/inc/filtres_ecrire.php
+++ b/ecrire/inc/filtres_ecrire.php
@@ -10,30 +10,30 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Fonctions utilisées au calcul des squelette du privé.
+ *
+ * @package SPIP\Filtres
+ */
if (!defined('_ECRIRE_INC_VERSION')) return;
include_spip('inc/filtres_boites');
include_spip('inc/boutons');
include_spip('inc/pipelines_ecrire');
-/**
- * Fonctions utilises au calcul des squelette du prive.
- */
-
/**
- * Retourne les parametres de personnalisation css de l'espace prive
- * (ltr et couleurs) ce qui permet une ecriture comme :
- * generer_url_public('style_prive', parametres_css_prive())
- * qu'il est alors possible de recuperer dans le squelette style_prive.html avec
+ * Retourne les paramètres de personnalisation css de l'espace privé
*
+ * Ces paramètres sont (ltr et couleurs) ce qui permet une écriture comme :
+ * generer_url_public('style_prive', parametres_css_prive())
+ * qu'il est alors possible de récuperer dans le squelette style_prive.html avec
+ *
* #SET{claire,##ENV{couleur_claire,edf3fe}}
* #SET{foncee,##ENV{couleur_foncee,3874b0}}
* #SET{left,#ENV{ltr}|choixsiegal{left,left,right}}
* #SET{right,#ENV{ltr}|choixsiegal{left,right,left}}
*
- * http://doc.spip.org/@parametres_css_prive
- *
* @return string
*/
function parametres_css_prive(){
@@ -63,10 +63,9 @@ function parametres_css_prive(){
/**
- * Afficher le selecteur de rubrique
- * qui permet de placer un objet dans la hierarchie des rubriques de SPIP
- *
- * http://doc.spip.org/@chercher_rubrique
+ * Afficher le sélecteur de rubrique
+ *
+ * Il permet de placer un objet dans la hiérarchie des rubriques de SPIP
*
* @param $titre
* @param $id_objet
@@ -134,8 +133,6 @@ function chercher_rubrique($titre,$id_objet, $id_parent, $objet, $id_secteur, $r
/**
* Tester si le site peut avoir des visiteurs
*
- * http://doc.spip.org/@avoir_visiteurs
- *
* @param bool $past
* si true, prendre en compte le fait que le site a *deja* des visiteurs
* comme le droit d'en avoir de nouveaux
@@ -153,12 +150,13 @@ function avoir_visiteurs($past=false, $accepter=true) {
}
/**
- * lister les status d'article visibles dans l'espace prive
+ * Lister les status d'article visibles dans l'espace prive
* en fonction du statut de l'auteur
- * pour l'extensibilie de SPIP, on se repose sur autoriser('voir','article')
- * en testant un a un les status presents en base
*
- * on memorise en static pour eviter de refaire plusieurs fois
+ * Pour l'extensibilie de SPIP, on se repose sur autoriser('voir','article')
+ * en testant un à un les status présents en base
+ *
+ * On mémorise en static pour éviter de refaire plusieurs fois.
*
* @param string $statut_auteur
* @return array
@@ -178,12 +176,11 @@ function statuts_articles_visibles($statut_auteur){
}
/**
- * Traduire le statut technique de l'auteur en langage comprehensible
- * si $statut=='nouveau' et que le statut en attente est fourni,
+ * Traduire le statut technique de l'auteur en langage compréhensible
+ *
+ * Si $statut=='nouveau' et que le statut en attente est fourni,
* le prendre en compte en affichant que l'auteur est en attente
*
- * http://doc.spip.org/@traduire_statut_auteur
- *
* @param string $statut
* @param string $attente
* @return string
@@ -219,7 +216,7 @@ function traduire_statut_auteur($statut,$attente=""){
}
/**
- * Afficher la mention des autres auteurs ayant modifie un objet
+ * Afficher la mention des autres auteurs ayant modifié un objet
*
* @param int $id_objet
* @param string $objet
@@ -301,14 +298,15 @@ function auteurs_lister_statuts($quoi='tous',$en_base=true) {
}
/**
- * Determiner la rubrique pour la creation d'un objet
- * heuristique : rubrique courante si possible,
- * sinon rubrique administree pour les admin restreint
- * sinon premiere rubrique de premier niveau autorisee que l'on trouve
+ * Déterminer la rubrique pour la création d'un objet heuristique
+ *
+ * Rubrique courante si possible,
+ * - sinon rubrique administrée pour les admin restreint
+ * - sinon première rubrique de premier niveau autorisée que l'on trouve
*
- * @param int $id_rubrique
- * @param string $objet
- * @return int
+ * @param int $id_rubrique Identifiant de rubrique (si connu)
+ * @param string $objet Objet en cours de création
+ * @return int Identifiant de la rubrique dans laquelle créer l'objet
*/
function trouver_rubrique_creer_objet($id_rubrique,$objet){
global $connect_id_rubrique;
diff --git a/ecrire/inc/pipelines.php b/ecrire/inc/pipelines.php
index 9b0043a3f2..7407dca0f8 100644
--- a/ecrire/inc/pipelines.php
+++ b/ecrire/inc/pipelines.php
@@ -11,7 +11,7 @@
\***************************************************************************/
/**
- * Fonctions déclarés dans des pipelines (espace public)
+ * Fonctions déclarées dans des pipelines (espace public)
*
* @package SPIP\Pipelines
**/
@@ -32,14 +32,14 @@ if (test_espace_prive())
*
* @internal
* Ne pas vérifier ici qu'on ne doublonne pas #INSERT_HEAD
- * car cela empeche un double appel (multi calcul en cache cool,
+ * car cela empêche un double appel (multi calcul en cache cool,
* ou erreur de l'espace privé)
*
* @see f_jQuery_prive()
* @link http://doc.spip.org/@f_jQuery
*
* @param string $texte Contenu qui sera inséré dans le head HTML
- * @return string Contenu complété des scripts javascripts, dont jQuery
+ * @return string Contenu qui sera inséré dans le head HTML
**/
function f_jQuery ($texte) {
$x = '';
@@ -60,8 +60,19 @@ function f_jQuery ($texte) {
return $texte;
}
-// Traiter var_recherche ou le referrer pour surligner les mots
-// http://doc.spip.org/@f_surligne
+
+/**
+ * Traiter var_recherche ou le referrer pour surligner les mots
+ *
+ * Surligne les mots de la recherche (si var_recherche est présent)
+ * ou des réferers (si la constante _SURLIGNE_RECHERCHE_REFERERS est
+ * définie à true) dans un texte HTML
+ *
+ * Cette fonction est appelée par le pipeline affichage_final
+ *
+ * @param string $texte Contenu de la page envoyée au navigateur
+ * @return string Contenu de la page envoyée au navigateur
+**/
function f_surligne ($texte) {
if (!$GLOBALS['html']) return $texte;
$rech = _request('var_recherche');
@@ -74,9 +85,24 @@ function f_surligne ($texte) {
return surligner_mots($texte, $rech);
}
-// Valider/indenter a la demande.
-// http://doc.spip.org/@f_tidy
+/**
+ * Indente un code HTML
+ *
+ * Indente et valide un code HTML si la globale 'xhtml' est
+ * définie à true.
+ *
+ * Cette fonction est appelée par le pipeline affichage_final
+ *
+ * @param string $texte Contenu de la page envoyée au navigateur
+ * @return string Contenu de la page envoyée au navigateur
+ **/
function f_tidy ($texte) {
+ /**
+ * Indentation à faire ?
+ *
+ * - true : actif.
+ * - false par défaut.
+ */
global $xhtml;
if ($xhtml # tidy demande
@@ -96,10 +122,19 @@ function f_tidy ($texte) {
return $texte;
}
-// Offre #INSERT_HEAD sur tous les squelettes (bourrin)
-// a activer dans mes_options via :
-// $spip_pipeline['affichage_final'] .= '|f_insert_head';
-// http://doc.spip.org/@f_insert_head
+
+/**
+ * Offre #INSERT_HEAD sur tous les squelettes (bourrin)
+ *
+ * À activer dans mes_options via :
+ * $GLOBALS['spip_pipeline']['affichage_final'] .= '|f_insert_head';
+ *
+ * Ajoute le contenu du pipeline insert head dans la page HTML
+ * si cela n'a pas été fait.
+ *
+ * @param string $texte Contenu de la page envoyée au navigateur
+ * @return string Contenu de la page envoyée au navigateur
+**/
function f_insert_head($texte) {
if (!$GLOBALS['html']) return $texte;
include_spip('public/admin'); // pour strripos
@@ -116,8 +151,15 @@ function f_insert_head($texte) {
return $texte;
}
-// Inserer au besoin les boutons admins
-// http://doc.spip.org/@f_admin
+
+/**
+ * Insérer au besoin les boutons admins
+ *
+ * Cette fonction est appelée par le pipeline affichage_final
+ *
+ * @param string $texte Contenu de la page envoyée au navigateur
+ * @return string Contenu de la page envoyée au navigateur
+**/
function f_admin ($texte) {
if (isset($GLOBALS['affiche_boutons_admin']) AND $GLOBALS['affiche_boutons_admin']) {
include_spip('public/admin');
@@ -129,13 +171,32 @@ function f_admin ($texte) {
return $texte;
}
+/**
+ * Actions sur chaque inclusion
+ *
+ * Appelle f_afficher_blocs_ecrire() sur les inclusions dans l'espace privé.
+ * Ne change rien dans l'espace public.
+ *
+ * Cette fonction est appelée par le pipeline recuperer_fond
+ *
+ * @see f_afficher_blocs_ecrire()
+ *
+ * @param array $flux Description et contenu de l'inclusion
+ * @return array $flux Description et contenu de l'inclusion
+**/
function f_recuperer_fond($flux) {
if (!test_espace_prive()) return $flux;
return f_afficher_blocs_ecrire($flux);
}
-// gerer le lancement du cron
-// si des taches sont en attentes
+/**
+ * Gérer le lancement du cron si des tâches sont en attente
+ *
+ * Cette fonction est appelée par le pipeline affichage_final
+ *
+ * @param string $texte Contenu de la page envoyée au navigateur
+ * @return string Contenu de la page envoyée au navigateur
+ */
function f_queue(&$texte){
// eviter une inclusion si rien a faire
diff --git a/ecrire/inc/pipelines_ecrire.php b/ecrire/inc/pipelines_ecrire.php
index 6fa1b341ec..128387c76d 100644
--- a/ecrire/inc/pipelines_ecrire.php
+++ b/ecrire/inc/pipelines_ecrire.php
@@ -11,7 +11,7 @@
\***************************************************************************/
/**
- * Fonctions déclarés dans des pipelines (espace privé)
+ * Fonctions déclarées dans des pipelines (espace privé)
*
* @package SPIP\Pipelines
**/
@@ -26,11 +26,6 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
* des js chargée peut être complété par le pipeline 'jquery_plugins'
*
* Cette fonction est appelée par le pipeline header_prive
- *
- * @internal
- * Ne pas vérifier ici qu'on ne doublonne pas #INSERT_HEAD
- * car cela empeche un double appel (multi calcul en cache cool,
- * ou erreur de l'espace privé)
*
* @see f_jQuery()
* @link http://doc.spip.org/@f_jQuery
diff --git a/ecrire/inc/queue.php b/ecrire/inc/queue.php
index 17dc3d145a..a88363650f 100644
--- a/ecrire/inc/queue.php
+++ b/ecrire/inc/queue.php
@@ -10,6 +10,11 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Gestion des queues de travaux
+ *
+ * @package SPIP\Queue
+**/
if (!defined("_ECRIRE_INC_VERSION")) return;
define('_JQ_SCHEDULED',1);
@@ -19,8 +24,9 @@ define('_JQ_PENDING',0);
#define('_JQ_NB_JOBS_OVERFLOW',10000); // nombre de jobs a partir duquel on force le traitement en fin de hit pour purger
/**
- * Ajouter une tache a la file
- * Les taches sont ensuites executees par date programmee croissant/priorite decroissante
+ * Ajouter une tâche à la file
+ *
+ * Les tâches sont ensuites exécutées par date programmée croissant/priorité décroissante
*
* @param $function
* The function name to call.
@@ -124,8 +130,7 @@ function queue_add_job($function, $description, $arguments = array(), $file = ''
}
/**
- * Purger la file de tache
- * et reprgrammer les taches periodiques
+ * Purger la file de tâche et reprgrammer les tâches périodiques
*
* @return void
*/
@@ -486,8 +491,11 @@ function queue_set_next_job_time($next) {
}
/**
- * html a ajouter a la page pour declencher le cron
- * ou rien si on a reussi a le lancer en asynchrone
+ * Déclenche le cron en asynchrone ou retourne le code HTML pour le déclencher
+ *
+ * Retourne le HTML à ajouter à la page pour declencher le cron
+ * ou rien si on a réussi à le lancer en asynchrone.
+ *
* @return string
*/
function queue_affichage_cron(){
--
GitLab