phpdoc en partie issu de la documentation collaborative de doc.spip.org

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;
 

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 :
  * 

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;

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)

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