From 2f164f3954406f0e23aafdb6376fdb704449543e Mon Sep 17 00:00:00 2001
From: Matthieu Marcillaud <marcimat@rezo.net>
Date: Mon, 25 Feb 2013 18:17:52 +0000
Subject: [PATCH] phpdoc en partie issu de la documentation collaborative de
doc.spip.org
---
ecrire/action/iconifier.php | 25 ++++++--
ecrire/base/abstract_sql.php | 2 +
ecrire/inc/headers.php | 19 +++++-
ecrire/inc/plugin.php | 29 +++++++--
ecrire/inc/utils.php | 121 ++++++++++++++++++++++++++++++-----
5 files changed, 166 insertions(+), 30 deletions(-)
diff --git a/ecrire/action/iconifier.php b/ecrire/action/iconifier.php
index 07de902da3..cee5a161be 100644
--- a/ecrire/action/iconifier.php
+++ b/ecrire/action/iconifier.php
@@ -14,7 +14,7 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
/**
* L'entree par l'action ne sert plus qu'a une retro compat eventuelle
- * le #FORMULAIRE_EDITER_LOGO utilise action_spip_image_ajouter_dist
+ * le `#FORMULAIRE_EDITER_LOGO` utilise action_spip_image_ajouter_dist
*/
function action_iconifier_dist()
{
@@ -48,9 +48,26 @@ function action_spip_image_effacer_dist($arg) {
// Ajouter un logo
//
-// $source = $_FILES[0]
-// $dest = arton12.xxx
-// http://doc.spip.org/@action_spip_image_ajouter_dist
+
+/**
+ * Permet d'ajouter un logo sur un objet, dont on passe le nom
+ *
+ * @example
+ * ```
+ * $logo = &$_FILES['logo_propose'];
+ * include_spip('action/iconifier');
+ * $spip_image_ajouter = charger_fonction('spip_image_ajouter','action');
+ * $spip_image_ajouter('arton'.$id_article,true,$logo);
+ * ```
+ *
+ * @param string $arg
+ * Nom de l'image pour l'objet tel que `arton4`
+ * @param bool $sousaction2
+ * - false pour prendre automatiquement le logo dans `$_FILES`
+ * - true pour le passer en 3e paramètre
+ * @param string $source
+ * Chemin du logo uploadé sur le serveur en attente d'utilisation
+**/
function action_spip_image_ajouter_dist($arg,$sousaction2,$source) {
global $formats_logos;
diff --git a/ecrire/base/abstract_sql.php b/ecrire/base/abstract_sql.php
index af56634b7f..5a76d913d2 100644
--- a/ecrire/base/abstract_sql.php
+++ b/ecrire/base/abstract_sql.php
@@ -600,6 +600,8 @@ function sql_replace_multi($table, $tab_couples, $desc=array(), $serveur='', $op
* Nom de la table
* @param string $exist
* true pour ajouter un test sur l'existence de la table, false sinon
+ * @param string $serveur
+ * Nom du connecteur
* @param bool|string $option
* Peut avoir 3 valeurs :
*
diff --git a/ecrire/inc/headers.php b/ecrire/inc/headers.php
index 20fc6e7b4e..063d75ed03 100644
--- a/ecrire/inc/headers.php
+++ b/ecrire/inc/headers.php
@@ -18,10 +18,23 @@
if (!defined('_ECRIRE_INC_VERSION')) return;
-// envoyer le navigateur sur une nouvelle adresse
-// en evitant les attaques par la redirection (souvent indique par 1 $_GET)
-// http://doc.spip.org/@redirige_par_entete
+/**
+ * Envoyer le navigateur sur une nouvelle adresse
+ *
+ * Le tout en évitant les attaques par la redirection (souvent indique par un `$_GET`)
+ *
+ * @example
+ * ```
+ * $redirect = parametre_url(urldecode(_request('redirect')),'id_article=' . $id_article);
+ * include_spip('inc/headers');
+ * redirige_par_entete($redirect);
+ * ```
+ *
+ * @param string $url URL de redirection
+ * @param string $equiv ?
+ * @param int $status Code de redirection (301 ou 302)
+**/
function redirige_par_entete($url, $equiv='', $status = 302) {
if (!in_array($status,array(301,302)))
$status = 302;
diff --git a/ecrire/inc/plugin.php b/ecrire/inc/plugin.php
index 532c34e8a3..2324df6a06 100644
--- a/ecrire/inc/plugin.php
+++ b/ecrire/inc/plugin.php
@@ -260,9 +260,10 @@ function liste_chemin_plugin($liste, $dir_plugins=_DIR_PLUGINS){
* Liste les chemins vers les plugins actifs du dossier fourni en argument
* a partir d'une liste d'elelements construits par plugin_valide_resume
*
+ * @param string $dir_plugins
+ * Chemin du répertoire de plugins
* @return array
*/
-// http://doc.spip.org/@liste_chemin_plugin_actifs
function liste_chemin_plugin_actifs($dir_plugins=_DIR_PLUGINS){
include_spip('plugins/installer');
return liste_chemin_plugin(liste_plugin_actifs(), $dir_plugins);
@@ -430,12 +431,26 @@ function actualise_plugins_actifs($pipe_recherche = false){
return ecrire_plugin_actifs('', $pipe_recherche, 'force');
}
-// mise a jour du meta en fonction de l'etat du repertoire
-// Les ecrire_meta() doivent en principe aussi initialiser la valeur a vide
-// si elle n'existe pas
-// risque de pb en php5 a cause du typage ou de null (verifier dans la doc php)
-// @return true/false si il y a du nouveau
-// http://doc.spip.org/@ecrire_plugin_actifs
+
+/**
+ * Modifie la liste des plugins actifs et recompile les fichiers caches
+ * qui leurs sont relatifs
+ *
+ * @note
+ * Les ecrire_meta() doivent en principe aussi initialiser la valeur a vide
+ * si elle n'existe pas risque de pb en php5 a cause du typage ou de null
+ * (verifier dans la doc php)
+ * @param string|string[] $plugin
+ * Plugin ou plugins concernés (leur chemin depuis le répertoire plugins)
+ * @param bool $pipe_recherche
+ * ?
+ * @param string $operation
+ * - raz : recalcule tout
+ * - ajoute : ajoute le plugin indiqué à la liste des plugins actifs
+ * - enleve : enleve le plugin indiqué de la liste des plugins actifs
+ * @return bool
+ * true|false si il y a du nouveau
+**/
function ecrire_plugin_actifs($plugin,$pipe_recherche=false,$operation='raz') {
// creer le repertoire cache/ si necessaire ! (installation notamment)
diff --git a/ecrire/inc/utils.php b/ecrire/inc/utils.php
index cade4a43b9..93f6fab766 100644
--- a/ecrire/inc/utils.php
+++ b/ecrire/inc/utils.php
@@ -87,15 +87,46 @@ function include_once_check($file){
return false;
}
-//
-// la fonction cherchant un fichier PHP dans le SPIP_PATH
-//
-// http://doc.spip.org/@include_spip
+
+/**
+ * Inclut un fichier PHP (en le cherchant dans les chemins)
+ *
+ * @api
+ * @uses find_in_path()
+ * @example
+ * ```
+ * include_spip('inc/texte');
+ * ```
+ *
+ * @param string $f
+ * Nom du fichier (sans l'extension)
+ * @param bool $include
+ * - true pour inclure le fichier,
+ * - false ne fait que le chercher
+ * @return string|bool
+ * - false : fichier introuvable
+ * - string : chemin du fichier trouvé
+**/
function include_spip($f, $include = true) {
return find_in_path($f . '.php', '', $include);
}
-
+/**
+ * Requiert un fichier PHP (en le cherchant dans les chemins)
+ *
+ * @uses find_in_path()
+ * @see include_spip()
+ * @example
+ * ```
+ * require_spip('inc/texte');
+ * ```
+ *
+ * @param string $f
+ * Nom du fichier (sans l'extension)
+ * @return string|bool
+ * - false : fichier introuvable
+ * - string : chemin du fichier trouvé
+**/
function require_spip($f) {
return find_in_path($f . '.php', '', 'required');
}
@@ -864,13 +895,39 @@ function texte_script($texte) {
return str_replace('\'', '\\\'', str_replace('\\', '\\\\', $texte));
}
-// Chaque appel a cette fonction ajoute un repertoire en tete du chemin courant (path)
-// si un repertoire lui est passe en parametre
-// retourne le chemin courant sinon, sous forme de array.
-// Si l'argument est de la forme dir1:dir2:dir3, ces 3 chemins sont places en tete
-// du path, dans cet ordre.
-// Exception: si un $dossier_squelette est defini, il reste en tete, pour raison historique
-// http://doc.spip.org/@_chemin
+
+/**
+ * Gestion des chemins (ou path) de recherche de fichiers par SPIP
+ *
+ * Empile de nouveaux chemins (à la suite de ceux déjà présent, mais avant
+ * le répertoire squelettes ou les dossiers squelettes), si un reéertoire
+ * (ou liste de répertoires séparés par `:`) lui est passé en paramètre.
+ *
+ * Ainsi, si l'argument est de la forme `dir1:dir2:dir3`, ces 3 chemins sont placés
+ * en tete du path, dans cet ordre (hormis squelettes & la globale
+ * $dossier_squelette si definie qui resteront devant)
+ *
+ * Retourne dans tous les cas la liste des chemins.
+ *
+ * @note
+ * Cette fonction est appelée à plusieurs endroits et crée une liste
+ * de chemins finale à peu près de la sorte :
+ *
+ * - dossiers squelettes (si globale précisée)
+ * - squelettes/
+ * - plugins (en fonction de leurs dépendances) : ceux qui dépendent
+ * d'un plugin sont devant eux (ils peuvent surcharger leurs fichiers)
+ * - racine du site
+ * - squelettes-dist/
+ * - prive/
+ * - ecrire/
+ *
+ * @param string $dir_path
+ * - Répertoire(s) à empiler au path
+ * - '' provoque un recalcul des chemins.
+ * @return array
+ * Liste des chemins, par ordre de priorité.
+**/
function _chemin($dir_path=NULL){
static $path_base = NULL;
static $path_full = NULL;
@@ -924,7 +981,15 @@ function _chemin($dir_path=NULL){
return $path_full;
}
-// http://doc.spip.org/@creer_chemin
+/**
+ * Retourne la liste des chemins connus de SPIP, dans l'ordre de priorité
+ *
+ * Recalcule la liste si le nom ou liste de dossier squelettes a changé.
+ *
+ * @uses _chemin()
+ *
+ * @return array Liste de chemins
+**/
function creer_chemin() {
$path_a = _chemin();
static $c = '';
@@ -1021,7 +1086,33 @@ function chemin_image($icone){
$GLOBALS['path_sig'] = '';
$GLOBALS['path_files'] = null;
-// http://doc.spip.org/@find_in_path
+/**
+ * Recherche un fichier dans les chemins de SPIP (squelettes, plugins, core)
+ *
+ * Retournera le premier fichier trouvé (ayant la plus haute priorité donc),
+ * suivant l'ordre des chemins connus de SPIP.
+ *
+ * @api
+ * @see charger_fonctions()
+ * @uses creer_chemin() Pour la liste des chemins.
+ * @example
+ * ```
+ * $f = find_in_path('css/perso.css');
+ * $f = find_in_path('perso.css', 'css');
+ * ```
+ *
+ * @param string $file
+ * Fichier recherché
+ * @param string $dirname
+ * Répertoire éventuel de recherche (est aussi extrait automatiquement de $file)
+ * @param bool|string $include
+ * - false : ne fait rien de plus
+ * - true : inclut le fichier (include_once)
+ * - 'require' : idem, mais tue le script avec une erreur si le fichier n'est pas trouvé.
+ * @return string|bool
+ * - string : chemin du fichier trouvé
+ * - false : fichier introuvable
+**/
function find_in_path ($file, $dirname='', $include=false) {
static $dirs=array();
static $inc = array(); # cf http://trac.rezo.net/trac/spip/changeset/14743
@@ -1396,8 +1487,6 @@ function url_de_($http,$host,$request,$prof=0){
* - false : l’URL sera complète et contiendra l’URL du site
* - true : l’URL sera relavive.
* - string : on transmet l'url à la fonction
- * @param string $action
- * - Fichier d'exécution public (spip.php par défaut)
* @return string URL
**/
function generer_url_ecrire($script='', $args="", $no_entities=false, $rel=false) {
--
GitLab