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

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

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;

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');

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)

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

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

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

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