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

ecrire/base/abstract_sql.php

@@ -66,19 +66,19 @@ function sql_serveur($ins_sql='', $serveur='', $continue=false) {
  * Demande si un charset est disponible
  *
  * Demande si un charset (tel que utf-8) est disponible
- * sur le gestionnaire de base de donnees de la connexion utilisee
+ * sur le gestionnaire de base de données de la connexion utilisée
  *
  * @api
  * @see sql_set_charset() pour utiliser un charset
  * 
  * @param string $charset
- * 		Le charset souhaite
+ *     Le charset souhaité
  * @param string $serveur
- * 		Le nom du connecteur
+ *     Le nom du connecteur
  * @param bool $option
- * 		Inutilise
+ *     Inutilise
  * @return string|bool
- * 		Retourne le nom du charset si effectivement trouve, sinon false.
+ *     Retourne le nom du charset si effectivement trouvé, sinon false.
 **/
 function sql_get_charset($charset, $serveur='', $option=true){
   // le nom http du charset differe parfois du nom SQL utf-8 ==> utf8 etc.
@@ -592,7 +592,25 @@ function sql_replace_multi($table, $tab_couples, $desc=array(), $serveur='', $op
 	return $r;
 }
 
-// http://doc.spip.org/@sql_drop_table
+/**
+ * Supprime une table SQL (structure et données)
+ *
+ * @api
+ * @param string $table
+ *     Nom de la table
+ * @param string $exist
+ *     true pour ajouter un test sur l'existence de la table, false sinon
+ * @param bool|string $option
+ *     Peut avoir 3 valeurs :
+ * 
+ *     - false : ne pas l'exécuter mais la retourner, 
+ *     - true : exécuter la requête
+ *     - 'continue' : ne pas échouer en cas de serveur sql indisponible
+ * @return bool|string
+ *     - True en cas de succès,
+ *     - Texte de la requête si demandé,
+ *     - False en cas d'erreur.
+**/
 function sql_drop_table($table, $exist='', $serveur='', $option=true)
 {
 	$f = sql_serveur('drop_table', $serveur,  $option==='continue' OR $option===false);
@@ -949,37 +967,38 @@ function sql_allfetsel($select = array(), $from = array(), $where = array(),
  * un unique champ demande
  * 
  * @example
- * 		<code>
- * 		$id_rubrique = sql_getfetsel('id_rubrique', 'spip_articles', 'id_article='.sql_quote($id_article));
- * 		</code>
+ *     ```
+ *     $id_rubrique = sql_getfetsel('id_rubrique', 'spip_articles', 'id_article='.sql_quote($id_article));
+ *     ```
  *
  * @api
  * @uses sql_fetsel()
  * 
  * @param array|string $select
- * 		Liste des champs a recuperer (Select)
+ *     Liste des champs à récupérer (Select)
  * @param array|string $from
- * 		Tables a consulter (From)
+ *     Tables à consulter (From)
  * @param array|string $where
- * 		Conditions a remplir (Where)
+ *     Conditions à remplir (Where)
  * @param array|string $groupby
- * 		Critere de regroupement (Group by)
+ *     Critère de regroupement (Group by)
  * @param array|string $orderby
- * 		Tableau de classement (Order By)
+ *     Tableau de classement (Order By)
  * @param string $limit
- * 		Critere de limite (Limit)
+ *     Critère de limite (Limit)
  * @param array $having
- * 		Tableau des des post-conditions a remplir (Having)
+ *     Tableau des des post-conditions à remplir (Having)
  * @param string $serveur
- * 		Le serveur sollicite (pour retrouver la connexion)
+ *     Le serveur sollicité (pour retrouver la connexion)
  * @param bool|string $option
- * 		Peut avoir 3 valeurs : 
- * 		- true -> executer la requete.
- * 		- continue -> ne pas echouer en cas de serveur sql indisponible.
- * 		- false -> ne pas l'executer mais la retourner.
+ *     Peut avoir 3 valeurs :
+ * 
+ *     - true -> executer la requete.
+ *     - continue -> ne pas echouer en cas de serveur sql indisponible.
+ *     - false -> ne pas l'executer mais la retourner.
  * 
  * @return mixed
- * 		Contenu de l'unique valeur demandee du premier enregistrement retourne
+ *     Contenu de l'unique valeur demandee du premier enregistrement retourne
  *
 **/
 function sql_getfetsel($select, $from = array(), $where = array(), $groupby = array(), 
@@ -1137,8 +1156,10 @@ function sql_hex($val, $serveur='', $option=true)
  * Echappe du contenu selon ce qu'attend le type de serveur SQL
  * et en fonction du type de contenu.
  * 
- * Cette fonction est automatiquement appelee par les fonctions sql_*q
- * tel que sql_instertq ou sql_updateq
+ * Permet entre autres de se protéger d'injections SQL.
+ * 
+ * Cette fonction est automatiquement appelée par les fonctions `sql_*q`
+ * tel que `sql_instertq` ou `sql_updateq`
  *
  * @api
  * @param string $val

ecrire/inc/utils.php

@@ -816,8 +816,25 @@ function quote_amp($u) {
 		"&",$u);
 }
 
-// Production d'une balise Script valide
-// http://doc.spip.org/@http_script
+
+/**
+ * Produit une balise `<script>` valide
+ *
+ * @example
+ *     ```
+ *     echo http_script('alert("ok");');
+ *     echo http_script('','js/jquery.js');
+ *     ```
+ * 
+ * @param string $script
+ *     Code source du script
+ * @param string $src
+ *     Permet de faire appel à un fichier javascript distant
+ * @param string $noscript
+ *     Contenu de la balise  `<noscript>`
+ * @return string
+ *     Balise HTML `<script>` et son contenu
+**/
 function http_script($script, $src='', $noscript='') {
 	static $done = array();
 

ecrire/plugins/installer.php

@@ -166,9 +166,20 @@ function spip_version_compare($v1,$v2,$op=null){
 	return $op?version_compare($v1, $v2,$op):version_compare($v1, $v2);
 }
 
-// Cette fonction retourne la meta "plugin" deserialisee
-// mais en fait une mise a jour qui aurait du intervenir au chgt de version
-// http://doc.spip.org/@liste_plugin_actifs
+
+/**
+ * Retourne un tableau des plugins activés sur le site
+ * 
+ * Retourne la meta `plugin` désérialisée.
+ * Chaque élément du tableau est lui-même un tableau contenant
+ * les détails du plugin en question : répertoire et version.
+ *
+ * @note
+ *   Si le contenu de la meta n’est pas un tableau, cette fonction transforme
+ *   l’ancien format en tableau sérialisé pour être conforme au nouveau fonctionnement (SPIP >= 1.9.2)
+ *
+ * @return array Tableau des plugins actifs
+**/
 function liste_plugin_actifs(){
 	$liste = isset($GLOBALS['meta']['plugin'])?$GLOBALS['meta']['plugin']:'';
 	if (!$liste) return array();

ecrire/req/mysql.php

@@ -126,14 +126,14 @@ function spip_mysql_set_charset($charset, $serveur='',$requeter=true,$requeter=t
 	return mysql_query($connexion['last'] = "SET NAMES "._q($charset));
 }
 
-// http://doc.spip.org/@spip_mysql_get_charset
-/**
 
- * @param array $charset
+/**
+ * Teste si le charset indiqué est disponible sur le serveur SQL
+ * 
+ * @param array|string $charset Nom du charset à tester.
  * @param string $serveur
  * @param bool $requeter
  * @return array
- *
  */
 function spip_mysql_get_charset($charset=array(), $serveur='',$requeter=true){
 	$connexion = &$GLOBALS['connexions'][$serveur ? strtolower($serveur) : 0];