diff --git a/ecrire/inc/envoyer_mail.php b/ecrire/inc/envoyer_mail.php
index d0abdbe3f855692550235d996b57724b2c4aaa82..050dcc8a9ba094a51cf029169886859307e7c121 100644
--- a/ecrire/inc/envoyer_mail.php
+++ b/ecrire/inc/envoyer_mail.php
@@ -10,6 +10,11 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Gestion des emails et de leur envoi
+ *
+ * @package SPIP\Core\Mail
+**/
if (!defined('_ECRIRE_INC_VERSION')) return;
include_spip('inc/charsets');
@@ -42,29 +47,28 @@ function nettoyer_caracteres_mail($t) {
/**
* Envoi d'un mail
- * http://doc.spip.org/@inc_envoyer_mail_dist
*
* @param string $destinataire
* @param string $sujet
* @param string|array $corps
- * au format string, c'est un corps d'email au format texte, comme supporte nativement par le core
- * au format array, c'est un corps etendu qui peut contenir
- * string texte : le corps d'email au format texte
- * string from : email de l'envoyeur (prioritaire sur argument $from de premier niveau, deprecie)
- * array headers : tableau d'en-tetes personalises, une entree par ligne d'en-tete
- * --- Support partiel par une fonction mail_embarquer_pieces_jointes a fournir, ---
- * --- chargee de convertir en texte encodee les pieces jointes ---
- * array pieces_jointes : listes de pieces a embarquer dans l'email, chacune au format array :
- * string chemin : chemin file system pour trouver le fichier a embarquer
- * string nom : nom du document tel qu'apparaissant dans l'email
- * string encodage : encodage a utiliser, parmi 'base64', '7bit', '8bit', 'binary', 'quoted-printable'
- * string mime : mime type du document
- * --- Non implemente ici ---
- * string html : le corps d'email au format html
- * string nom_envoyeur : un nom d'envoyeur pour completer l'email from
- * string cc : destinataires en copie conforme
- * string bcc : destinataires en copie conforme cachee
- * string adresse_erreur : addresse de retour en cas d'erreur d'envoi
+ * - au format string, c'est un corps d'email au format texte, comme supporte nativement par le core
+ * - au format array, c'est un corps etendu qui peut contenir
+ * - string texte : le corps d'email au format texte
+ * - string from : email de l'envoyeur (prioritaire sur argument $from de premier niveau, deprecie)
+ * - array headers : tableau d'en-tetes personalises, une entree par ligne d'en-tete
+ * --- Support partiel par une fonction mail_embarquer_pieces_jointes a fournir, ---
+ * --- chargee de convertir en texte encodee les pieces jointes ---
+ * - array pieces_jointes : listes de pieces a embarquer dans l'email, chacune au format array :
+ * - string chemin : chemin file system pour trouver le fichier a embarquer
+ * - string nom : nom du document tel qu'apparaissant dans l'email
+ * - string encodage : encodage a utiliser, parmi 'base64', '7bit', '8bit', 'binary', 'quoted-printable'
+ * - string mime : mime type du document
+ * --- Non implemente ici ---
+ * - string html : le corps d'email au format html
+ * - string nom_envoyeur : un nom d'envoyeur pour completer l'email from
+ * - string cc : destinataires en copie conforme
+ * - string bcc : destinataires en copie conforme cachee
+ * - string adresse_erreur : addresse de retour en cas d'erreur d'envoi
* @param string $from (deprecie, utiliser l'entree from de $corps)
* @param string $headers (deprecie, utiliser l'entree headers de $corps)
* @return bool
diff --git a/ecrire/inc/install.php b/ecrire/inc/install.php
index 65e4a6a6463a3c1d739242ed3979887060dbe5bd..bc142d880d7f03aa0d774e7c0a2071bb62cff78d 100644
--- a/ecrire/inc/install.php
+++ b/ecrire/inc/install.php
@@ -240,7 +240,12 @@ function info_etape($titre, $complement = ''){
($complement ? "".$complement."\n":'');
}
-// http://doc.spip.org/@bouton_suivant
+/**
+ * Retourne le code HTML d'un bouton `suivant>>` pour les phases d'installation
+ *
+ * @param string $code Texte du bouton
+ * @return string Code HTML du bouton
+**/
function bouton_suivant($code = '') {
if($code=='') $code = _T('bouton_suivant');
static $suivant = 0;
diff --git a/ecrire/inc/lang.php b/ecrire/inc/lang.php
index 8f4d57b6847f46aa9d4de712f2d2d8ad495685a4..30a1c57d7e294eae1ffde7e88d72eb4074bbb8db 100644
--- a/ecrire/inc/lang.php
+++ b/ecrire/inc/lang.php
@@ -92,7 +92,17 @@ function approcher_langue ($trads, $lang='') {
return '';
}
-// http://doc.spip.org/@traduire_nom_langue
+/**
+ * Traduit un code de langue (fr, en, etc...) vers le nom de la langue
+ * en toute lettres dans cette langue (français, English, etc....).
+ *
+ * Si le spip ne connait pas le nom de la langue, il retourne le code
+ *
+ * @param string $lang
+ * Code de langue
+ * @return string
+ * Nom de la langue, sinon son code.
+**/
function traduire_nom_langue($lang) {
include_spip('inc/lang_liste');
include_spip('inc/charsets');
diff --git a/ecrire/inc/mail.php b/ecrire/inc/mail.php
index 82c12be15b2993dbcc11e056e9f504151e3ff30b..3456a9e83b3e165288d2e28213ef6fe3fdba036d 100644
--- a/ecrire/inc/mail.php
+++ b/ecrire/inc/mail.php
@@ -10,15 +10,22 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
-##
-## Module de compatibilite ascendante : desormais inc/envoyer_mail
-##
+/**
+ * Module de compatibilite ascendante : desormais inc/envoyer_mail
+ *
+ * @deprecated Utiliser inc/envoyer_mail
+ * @package SPIP\Core\Mail
+ */
if (!defined('_ECRIRE_INC_VERSION')) return;
if (!function_exists('envoyer_mail')) {
define('_FUNCTION_ENVOYER_MAIL', charger_fonction('envoyer_mail', 'inc'));
-// http://doc.spip.org/@envoyer_mail
+ /**
+ * Envoie un mail.
+ * @uses inc_envoyer_mail_dist()
+ * @deprecated Utiliser inc_envoyer_mail_dist() via charger_fonction()
+ **/
function envoyer_mail() {
$args = func_get_args();
if (_FUNCTION_ENVOYER_MAIL)
diff --git a/ecrire/inc/presentation.php b/ecrire/inc/presentation.php
index 383fb130ae469b1897d6f0570f7834406911efa0..fd435d811a565dd1bb8a4ff40f5a606761e71623 100644
--- a/ecrire/inc/presentation.php
+++ b/ecrire/inc/presentation.php
@@ -10,6 +10,11 @@
* Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne. *
\***************************************************************************/
+/**
+ * Fonctions pour l'affichage privé des pages exec PHP
+ *
+ * @package SPIP\Core\Presentation
+**/
if (!defined('_ECRIRE_INC_VERSION')) return;
include_spip('inc/presentation_mini');
@@ -73,7 +78,13 @@ function fin_boite_alerte() {return fin_cadre('alerte');}
function debut_boite_info() {return debut_cadre('info', '', '', '', '', '');}
function fin_boite_info() {return fin_cadre('info');}
-// http://doc.spip.org/@gros_titre
+/**
+ * Affiche le titre d’une page de l’interface privée. Utilisée par la plupart des fichiers `exec/xx.php`.
+ *
+ * @param string $titre Le titre en question
+ * @param string $ze_logo Une image de logo
+ * @return string Code PHP.
+**/
function gros_titre($titre, $ze_logo=''){return "<h1 class='grostitre'>" . $ze_logo.' ' . typo($titre)."</h1>\n";}
// La boite des raccourcis
@@ -140,4 +151,4 @@ function icone_horizontale($texte, $lien, $fond, $fonction="", $dummy="", $javas
return $retour;
}
-?>
\ No newline at end of file
+?>
diff --git a/ecrire/inc/utils.php b/ecrire/inc/utils.php
index 0a0b7813bb4c927d2a3a9724157538b1ca282098..2d1cebf70a60ed9fd05e80b418e5604d1b9a8acf 100644
--- a/ecrire/inc/utils.php
+++ b/ecrire/inc/utils.php
@@ -233,9 +233,20 @@ function journal($phrase, $opt = array()) {
$journal($phrase, $opt);
}
-// Renvoie le _GET ou le _POST emis par l'utilisateur
-// ou pioche dans $c si c'est un array()
-// http://doc.spip.org/@_request
+
+/**
+ * Renvoie le `$_GET` ou le `$_POST` émis par l'utilisateur
+ * ou pioché dans un tableau transmis
+ *
+ * @api
+ * @param string $var
+ * Clé souhaitée
+ * @param bool|array $var
+ * Tableau transmis (sinon cherche dans GET ou POST)
+ * @return mixed|null
+ * - null si la clé n'a pas été trouvée
+ * - la valeur de la clé sinon.
+**/
function _request($var, $c=false) {
if (is_array($c))
@@ -261,9 +272,20 @@ function _request($var, $c=false) {
return $a;
}
-// Methode set de la fonction _request()
-// Attention au cas ou l'on fait set_request('truc', NULL);
-// http://doc.spip.org/@set_request
+
+/**
+ * Affecte une valeur à une clé (pour usage avec `_request()`)
+ *
+ * @see _request() Pour obtenir la valeur
+ * @note Attention au cas ou l'on fait `set_request('truc', NULL);`
+ *
+ * @param string $var Nom de la clé
+ * @param string $val Valeur à affecter
+ * @param bool|array $c Tableu de données (sinon utilise `$_GET` et `$_POST`)
+ * @return array|bool
+ * - array $c complété si un $c est transmis,
+ * - false sinon
+**/
function set_request($var, $val = NULL, $c=false) {
if (is_array($c)) {
unset($c[$var]);
@@ -282,8 +304,8 @@ function set_request($var, $val = NULL, $c=false) {
/**
- * Tester si une url est absolue
- * @param $url
+ * Tester si une URL est absolue
+ * @param string $url
* @return bool
*/
function tester_url_absolue($url){
@@ -2087,29 +2109,31 @@ function erreur_squelette($message='', $lieu='') {
* $fond peut etre un nom de squelette, ou une liste de squelette au format array.
* Dans ce dernier cas, les squelettes sont tous evalues et mis bout a bout
* $options permet de selectionner les options suivantes :
- * trim => true (valeur par defaut) permet de ne rien renvoyer si le fond ne produit que des espaces ;
- * raw => true permet de recuperer la strucure $page complete avec entetes et invalideurs
+ *
+ * - trim => true (valeur par defaut) permet de ne rien renvoyer si le fond ne produit que des espaces ;
+ * - raw => true permet de recuperer la strucure $page complete avec entetes et invalideurs
* pour chaque $fond fourni.
*
* @api
* @param string/array $fond
- * Le ou les squelettes à utiliser, sans l'extension, {@example prive/liste/auteurs}
- * Le fichier sera retrouvé dans la liste des chemins connus de SPIP (squelettes, plugins, spip)
+ * - Le ou les squelettes à utiliser, sans l'extension, {@example prive/liste/auteurs}
+ * - Le fichier sera retrouvé dans la liste des chemins connus de SPIP (squelettes, plugins, spip)
* @param array $contexte
- * Informations de contexte envoyées au squelette, {@example array('id_rubrique' => 8)}
- * La langue est transmise automatiquement (sauf option étoile).
+ * - Informations de contexte envoyées au squelette, {@example array('id_rubrique' => 8)}
+ * - La langue est transmise automatiquement (sauf option étoile).
* @param array $options
- * Options complémentaires :
- * - trim : applique un trim sur le résultat (true par défaut)
- * - raw : retourne un tableau d'information sur le squelette (false par défaut)
- * - etoile : ne pas transmettre la langue au contexte automatiquement (false par défaut),
- * équivalent de INCLURE*
- * - ajax : gere les liens internes du squelette en ajax (équivalent du paramètre {ajax})
+ * Options complémentaires :
+ *
+ * - trim : applique un trim sur le résultat (true par défaut)
+ * - raw : retourne un tableau d'information sur le squelette (false par défaut)
+ * - etoile : ne pas transmettre la langue au contexte automatiquement (false par défaut),
+ * équivalent de INCLURE*
+ * - ajax : gere les liens internes du squelette en ajax (équivalent du paramètre {ajax})
* @param string $connect
- * Non du connecteur de bdd a utiliser
+ * Non du connecteur de bdd a utiliser
* @return string|array
- * Contenu du squelette calculé
- * ou tableau d'information sur le squelette.
+ * - Contenu du squelette calculé
+ * - ou tableau d'information sur le squelette.
*/
function recuperer_fond($fond, $contexte=array(), $options = array(), $connect='') {
if (!function_exists('evaluer_fond'))
diff --git a/ecrire/public/balises.php b/ecrire/public/balises.php
index 76d94468c6dcacfd172c9340f9c6d0627e21d7f9..cdeb4191a975ca0a282db282a98270532b5f2daf 100644
--- a/ecrire/public/balises.php
+++ b/ecrire/public/balises.php
@@ -30,6 +30,7 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
/**
* Retourne le code PHP d'un argument de balise s'il est présent
*
+ * @uses calculer_liste()
* @example
* ```
* // Retourne le premier argument de la balise
diff --git a/ecrire/public/boucles.php b/ecrire/public/boucles.php
index b15defc4803e71d702eef9520fbf903d6f4ee94d..40b577b372241fdd778dfcf4bf43023148ca63b8 100644
--- a/ecrire/public/boucles.php
+++ b/ecrire/public/boucles.php
@@ -38,8 +38,10 @@ function boucle_DEFAUT_dist($id_boucle, &$boucles) {
/**
* Compile une boucle récursive
*
- * <BOUCLE(BOUCLE)>
+ * `<BOUCLE(BOUCLE)>`
*
+ * @link http://www.spip.net/914
+ *
* @param string $id_boucle
* Identifiant de la boucle
* @param array $boucles
@@ -55,9 +57,11 @@ function boucle_BOUCLE_dist($id_boucle, &$boucles) {
/**
* Compile une boucle HIERARCHIE
*
- * <BOUCLE(HIERARCHIE)>
+ * La boucle `<BOUCLE(HIERARCHIE)>` retourne la liste des RUBRIQUES
+ * qui mènent de la racine du site à la rubrique ou à l’article en cours.
*
* Cette boucle (aliasée sur la table RUBRIQUES)
+ *
* - recherche un id_rubrique dans les boucles parentes,
* - extrait sa hiérarchie, en prenant ou non la rubrique en cours en fonction du critère {tout}
* - crée une condition WHERE avec ces identifiants ansi qu'une clause ORDER
@@ -66,6 +70,8 @@ function boucle_BOUCLE_dist($id_boucle, &$boucles) {
* Le code compilé calculant la hierarchie est ajouté au tout début de la
* fonction de boucle et quitte la boucle si aucune rubrique n'est trouvée.
*
+ * @link http://www.spip.net/913
+ *
* @param string $id_boucle
* Identifiant de la boucle
* @param array $boucles