From 662b48f193227f732208eebcab6f6fa0d14dbdda Mon Sep 17 00:00:00 2001
From: Matthieu Marcillaud <marcimat@rezo.net>
Date: Mon, 25 Feb 2013 19:23:57 +0000
Subject: [PATCH] phpdoc en partie issu de la documentation collaborative de
doc.spip.org
---
ecrire/base/abstract_sql.php | 2 ++
ecrire/base/connect_sql.php | 23 +++++++++++++++++-----
ecrire/inc/filtres.php | 15 ++++++++++++++-
ecrire/inc/pipelines.php | 19 +++++++++++++-----
ecrire/inc/session.php | 6 +++---
ecrire/inc/utils.php | 37 ++++++++++++++++++++++++++----------
ecrire/index.php | 7 +++++++
ecrire/req/mysql.php | 8 +++++---
8 files changed, 90 insertions(+), 27 deletions(-)
diff --git a/ecrire/base/abstract_sql.php b/ecrire/base/abstract_sql.php
index 5a76d913d2..c6bd647120 100644
--- a/ecrire/base/abstract_sql.php
+++ b/ecrire/base/abstract_sql.php
@@ -637,6 +637,8 @@ function sql_drop_view($table, $exist='', $serveur='', $option=true)
* Retourne une ressource de la liste des tables de la base de données
*
* @api
+ * @see sql_alltable()
+ *
* @param string $spip
* Filtre sur tables retournées
* - NULL : retourne les tables SPIP uniquement (tables préfixées avec le préfixe de la connexion)
diff --git a/ecrire/base/connect_sql.php b/ecrire/base/connect_sql.php
index ccecb8ed65..1660f68e6d 100644
--- a/ecrire/base/connect_sql.php
+++ b/ecrire/base/connect_sql.php
@@ -10,12 +10,15 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Utilitaires indispensables autour des serveurs SQL
+ *
+ * @package SPIP\Core\SQL
+**/
if (!defined('_ECRIRE_INC_VERSION')) return;
include_spip('base/objets');
-//
-// Utilitaires indispensables autour des serveurs SQL
-//
+
// API d'appel aux bases de donnees:
// on charge le fichier config/$serveur ($serveur='connect' pour le principal)
@@ -342,8 +345,18 @@ function query_reinjecte_textes($query, $textes){
return $query;
}
-// Pour compatibilite. Ne plus utiliser.
-// http://doc.spip.org/@spip_query
+
+/**
+ * Exécute une requête sur le serveur SQL
+ *
+ * @see sql_query()
+ * @deprecated Pour compatibilité. Utiliser `sql_query()` ou l'API `sql_*`.
+ * @param string $query Texte de la requête
+ * @param string $serveur Nom du connecteur pour la base de données
+ * @return bool|mixed
+ * - false si on ne peut pas exécuter la requête
+ * - indéfini sinon.
+**/
function spip_query($query, $serveur='') {
global $spip_sql_version;
$f = spip_connect_sql($spip_sql_version, 'query', $serveur, true);
diff --git a/ecrire/inc/filtres.php b/ecrire/inc/filtres.php
index ad26a5cf47..e543f4c7b8 100644
--- a/ecrire/inc/filtres.php
+++ b/ecrire/inc/filtres.php
@@ -2453,7 +2453,20 @@ function form_hidden($action) {
return join("", $hidden);
}
-// http://doc.spip.org/@filtre_bornes_pagination_dist
+/**
+ * Calcule les bornes d'une pagination
+ *
+ * @filtre bornes_pagination
+ *
+ * @param int $courante
+ * Page courante
+ * @param int $nombre
+ * Nombre de pages
+ * @param int $max
+ * Nombre d'éléments par page
+ * @return int[]
+ * Liste (première page, dernière page).
+**/
function filtre_bornes_pagination_dist($courante, $nombre, $max = 10) {
if($max<=0 OR $max>=$nombre)
return array(1, $nombre);
diff --git a/ecrire/inc/pipelines.php b/ecrire/inc/pipelines.php
index 479b025f4c..25ac26d044 100644
--- a/ecrire/inc/pipelines.php
+++ b/ecrire/inc/pipelines.php
@@ -31,12 +31,13 @@ if (test_espace_prive())
* Cette fonction est appelée par le pipeline insert_head
*
* @internal
- * Ne pas vérifier ici qu'on ne doublonne pas #INSERT_HEAD
+ * Ne pas vérifier ici qu'on ne doublonne pas `#INSERT_HEAD`
* 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
+ * @pipeline insert_head
+ * @pipeline_appel jquery_plugins
*
* @param string $texte Contenu qui sera inséré dans le head HTML
* @return string Contenu qui sera inséré dans le head HTML
@@ -69,6 +70,8 @@ function f_jQuery ($texte) {
* définie à true) dans un texte HTML
*
* Cette fonction est appelée par le pipeline affichage_final
+ *
+ * @pipeline affichage_final
*
* @param string $texte Contenu de la page envoyée au navigateur
* @return string Contenu de la page envoyée au navigateur
@@ -93,6 +96,8 @@ function f_surligne ($texte) {
*
* Cette fonction est appelée par le pipeline affichage_final
*
+ * @pipeline affichage_final
+ *
* @param string $texte Contenu de la page envoyée au navigateur
* @return string Contenu de la page envoyée au navigateur
**/
@@ -124,14 +129,16 @@ function f_tidy ($texte) {
/**
- * Offre #INSERT_HEAD sur tous les squelettes (bourrin)
+ * Offre `#INSERT_HEAD` sur tous les squelettes (bourrin)
*
* À activer dans mes_options via :
- * $GLOBALS['spip_pipeline']['affichage_final'] .= '|f_insert_head';
+ * `$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.
*
+ * @pipeline_appel insert_head
+ *
* @param string $texte Contenu de la page envoyée au navigateur
* @return string Contenu de la page envoyée au navigateur
**/
@@ -156,7 +163,8 @@ function f_insert_head($texte) {
* Insérer au besoin les boutons admins
*
* Cette fonction est appelée par le pipeline affichage_final
- *
+ * @pipeline affichage_final
+ *
* @param string $texte Contenu de la page envoyée au navigateur
* @return string Contenu de la page envoyée au navigateur
**/
@@ -192,6 +200,7 @@ function f_admin ($texte) {
* Cette fonction est appelée par le pipeline recuperer_fond
*
* @see f_afficher_blocs_ecrire()
+ * @pipeline recuperer_fond
*
* @param array $flux Description et contenu de l'inclusion
* @return array $flux Description et contenu de l'inclusion
diff --git a/ecrire/inc/session.php b/ecrire/inc/session.php
index c1a39030d2..880b5df1b3 100644
--- a/ecrire/inc/session.php
+++ b/ecrire/inc/session.php
@@ -88,11 +88,11 @@ function supprimer_sessions($id_auteur, $toutes=true, $actives=true) {
}
/**
- * Ajoute une session pour l'auteur decrit par un tableau issu d'un SELECT-SQL
- *
- * http://doc.spip.org/@ajouter_session
+ * Ajoute une session pour l'auteur décrit par un tableau issu d'un SELECT-SQL
*
* @param array $auteur
+ * Description de la session de l'auteur. Peut contenir (par exemple)
+ * les clés : id_auteur, nom, login, email, statut, lang, ...
* @return bool|string
*/
function ajouter_session($auteur) {
diff --git a/ecrire/inc/utils.php b/ecrire/inc/utils.php
index 93f6fab766..70b5f7b454 100644
--- a/ecrire/inc/utils.php
+++ b/ecrire/inc/utils.php
@@ -20,17 +20,30 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
/**
- * charge un fichier perso ou, a defaut, standard
- * et retourne si elle existe le nom de la fonction homonyme (exec_$nom),
- * ou de suffixe _dist
- * Peut etre appelee plusieurs fois, donc optimiser
- *
- * http://doc.spip.org/@charger_fonction
+ * Cherche une fonction surchargeable et en retourne le nom exact,
+ * après avoir chargé le fichier la contenant si nécessaire.
+ *
+ * Charge un fichier (suivant les chemins connus) et retourne si elle existe
+ * le nom de la fonction homonyme `$dir_$nom`, ou suffixé `$dir_$nom_dist`
+ *
+ * Peut être appelé plusieurs fois, donc optimisé.
*
+ * @api
+ * @uses include_spip() Pour charger le fichier
+ * @example
+ * ```
+ * $envoyer_mail = charger_fonction('envoyer_mail', 'inc');
+ * $envoyer_mail($email, $sujet, $texte);
+ * ```
+ *
* @param string $nom
+ * Nom de la fonction (et du fichier)
* @param string $dossier
+ * Nom du dossier conteneur
* @param bool $continue
+ * true pour ne pas râler si la fonction n'est pas trouvée
* @return string
+ * Nom de la fonction, ou false.
*/
function charger_fonction($nom, $dossier='exec', $continue=false) {
static $echecs = array();
@@ -511,15 +524,19 @@ function self($amp = '&', $root = false) {
return $url;
}
-// Indique si on est dans l'espace prive
-// http://doc.spip.org/@test_espace_prive
+
+/**
+ * Indique si on est dans l'espace prive
+ *
+ * @return bool
+ * true si c'est le cas, false sinon.
+ */
function test_espace_prive() {
return defined('_ESPACE_PRIVE') ? _ESPACE_PRIVE : false;
}
/**
- * Verifie la presence d'un plugin active, identifie par son prefix
- *
+ * Vérifie la présence d'un plugin actif, identifié par son préfixe
*
* @param string $plugin
* @return bool
diff --git a/ecrire/index.php b/ecrire/index.php
index ccd6119200..2d5e2a57bb 100644
--- a/ecrire/index.php
+++ b/ecrire/index.php
@@ -10,6 +10,13 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Fichier d'exécution de l'interface privée
+ *
+ * @package SPIP\Core\Chargement
+**/
+
+/** Drapeau indiquant que l'on est dans l'espace privé */
define('_ESPACE_PRIVE', true);
if (!defined('_ECRIRE_INC_VERSION')) include 'inc_version.php';
diff --git a/ecrire/req/mysql.php b/ecrire/req/mysql.php
index 6dd9ff15fb..90d428d18a 100644
--- a/ecrire/req/mysql.php
+++ b/ecrire/req/mysql.php
@@ -1228,12 +1228,14 @@ function spip_versions_mysql() {
return function_exists('mysql_query');
}
-// Tester si mysql ne veut pas du nom de la base dans les requetes
-// http://doc.spip.org/@test_rappel_nom_base_mysql
/**
- * @param $server_db
+ * Tester si mysql ne veut pas du nom de la base dans les requêtes
+ *
+ * @param string $server_db
* @return string
+ * - chaîne vide si nom de la base utile
+ * - chaîne : code compilé pour le faire désactiver par SPIP sinon
*/
function test_rappel_nom_base_mysql($server_db)
{
--
GitLab