diff --git a/ecrire/action/ajouter_lien.php b/ecrire/action/ajouter_lien.php
index bb14159b6f570ce61424bda4976802aacbeaa50d..b18fea3f55e6ec397934bd9b241d5ae8d3739a35 100644
--- a/ecrire/action/ajouter_lien.php
+++ b/ecrire/action/ajouter_lien.php
@@ -10,8 +10,27 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action ajouter_lien
+ *
+ * @package SPIP\Core\Liens
+**/
+
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
+/**
+ * Action pour lier 2 objets entre eux
+ *
+ * L'argument attendu est `objet1-id1-objet2-id2` (type d'objet, identifiant)
+ * tel que `mot-7-rubrique-3`.
+ *
+ * @uses objet_associer()
+ * 
+ * @param null|string $arg
+ *     Clé des arguments. En absence utilise l'argument
+ *     de l'action sécurisée.
+ * @return void
+ */
 function action_ajouter_lien_dist($arg=null){
 	if (is_null($arg)){
 		$securiser_action = charger_fonction('securiser_action','inc');
diff --git a/ecrire/action/annuler_job.php b/ecrire/action/annuler_job.php
index 762dc924ff812e23589b6d78eaae82a6731fe0be..4c7528c50adf8e678632c82142708610ebcd6039 100644
--- a/ecrire/action/annuler_job.php
+++ b/ecrire/action/annuler_job.php
@@ -10,6 +10,12 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action annuler_job
+ *
+ * @package SPIP\Core\Job
+**/
+
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 /**
@@ -27,4 +33,4 @@ function action_annuler_job_dist(){
 	}
 }
 
-?>
\ No newline at end of file
+?>
diff --git a/ecrire/action/calculer_taille_cache.php b/ecrire/action/calculer_taille_cache.php
index 82dc02d84f07c8d84691345bbf80f74828dce082..12ba5728e763af6277e10a3e53e5d314b79dea8e 100644
--- a/ecrire/action/calculer_taille_cache.php
+++ b/ecrire/action/calculer_taille_cache.php
@@ -10,6 +10,11 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action calculer_taille_cache
+ *
+ * @package SPIP\Core\Cache
+**/
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 
@@ -17,7 +22,12 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
 /**
  * Calculer la taille du cache ou du cache image pour l'afficher en ajax sur la page d'admin de SPIP
  *
+ * Si l'argument reçu est 'images', c'est la taille du cache _DIR_VAR qui est calculé,
+ * sinon celle du cache des squelettes (approximation)
+ * 
  * @param string|null $arg
+ *     Argument attendu. En absence utilise l'argument
+ *     de l'action sécurisée.
  */
 function action_calculer_taille_cache_dist($arg=null){
 	if (is_null($arg)){
@@ -64,10 +74,8 @@ function action_calculer_taille_cache_dist($arg=null){
 /**
  * Calculer la taille d'un dossier, sous dossiers inclus
  *
- * http://doc.spip.org/@calculer_taille_dossier
- *
- * @param $dir
- * @return int
+ * @param string $dir Répertoire dont on souhaite évaluer la taille
+ * @return int Taille en octets
  */
 function calculer_taille_dossier ($dir) {
 	$handle = @opendir($dir);
@@ -86,4 +94,4 @@ function calculer_taille_dossier ($dir) {
 	return $taille;
 }
 
-?>
\ No newline at end of file
+?>
diff --git a/ecrire/action/confirmer_email.php b/ecrire/action/confirmer_email.php
index dfa68bc29ac84a2e4d7f07d464a05f90030d7dfc..3998cf0092e5498a72bf999627f61747525fbc78 100644
--- a/ecrire/action/confirmer_email.php
+++ b/ecrire/action/confirmer_email.php
@@ -10,6 +10,12 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action confirmer_email
+ * 
+ * @package SPIP\Core\Inscription
+ */
+
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 /**
diff --git a/ecrire/action/confirmer_inscription.php b/ecrire/action/confirmer_inscription.php
index 3c731d545973f94958cd3fbad784c544634df412..ad30120a7466a0daa7354751c2f6f66c01ab1ad6 100644
--- a/ecrire/action/confirmer_inscription.php
+++ b/ecrire/action/confirmer_inscription.php
@@ -10,6 +10,12 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action confirmer_inscription
+ * 
+ * @package SPIP\Core\Inscription
+ */
+ 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 /**
diff --git a/ecrire/action/converser.php b/ecrire/action/converser.php
index e4f9d01103e7fecf7eeddd0181ce6f9ab2821b10..6d51a8118cdbdb9f7b2996a9d443044faa515012 100644
--- a/ecrire/action/converser.php
+++ b/ecrire/action/converser.php
@@ -10,6 +10,11 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action converser qui permet changer de langue
+ *
+ * @package SPIP\Core\Langue
+**/
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 include_spip('inc/cookie');
@@ -17,10 +22,9 @@ include_spip('inc/cookie');
 /**
  * Point d'entrée pour changer de langue
  * 
- * pas de secu si espace public ou login ou installation
- * mais alors on n'accede pas a la base, on pose seulement le cookie.
- * 
- * @link http://doc.spip.org/@action_converser_dist
+ * Pas de secu si espace public ou login ou installation
+ * mais alors on n'accède pas à la base, on pose seulement le cookie.
+ *
  * @return void
  */
 function action_converser_dist()
@@ -44,7 +48,6 @@ function action_converser_dist()
  * Cette fonction prépare le travail de changement de langue
  * en récupérant la bonne variable de langue
  * 
- * @link http://doc.spip.org/@action_converser_changer_langue
  * @global array $GLOBALS['visiteur_session']
  * @param bool $update_session 
  * @return string
@@ -73,7 +76,6 @@ function action_converser_changer_langue($update_session){
 /**
  * Cette fonction effectue le travail de changement de langue
  * 
- * @link http://doc.spip.org/@action_converser_post
  * @param string $lang 
  * @param bool $ecrire 
  * @return void
diff --git a/ecrire/action/cookie.php b/ecrire/action/cookie.php
index 4fef4356012106d61926efe2a146bd6c475f6b87..0ee30835be249bd98da965393ea6043255d2cbd1 100644
--- a/ecrire/action/cookie.php
+++ b/ecrire/action/cookie.php
@@ -10,19 +10,24 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action cookie
+ * 
+ * @package SPIP\Core\Inscription
+ */
+ 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 include_spip('inc/actions');
 include_spip('inc/cookie');
 
 /**
- * Cette fonction traite les cookies posés au moment de d'authentification standard
+ * Cette fonction traite les cookies posés au moment de l'authentification standard
  * ou vérifie que l'authentification HTTP est correcte
  * 
- * @link http://doc.spip.org/@action_cookie_dist
- * @param string $set_cookie_admin 
- * @param string $change_session 
- * @global bool $GLOBALS['ignore_auth_http']
+ * @global bool ignore_auth_http
+ * @param string|null $set_cookie_admin 
+ * @param string|null $change_session 
  * @return void
  */
 function action_cookie_dist($set_cookie_admin=null, $change_session = null) {
diff --git a/ecrire/action/debloquer_edition.php b/ecrire/action/debloquer_edition.php
index 63ae9dc8f1262c9833a4e8459f68374f29e70c9b..1916f5f9865ae0c35e0e0c85fa6915d752156610 100644
--- a/ecrire/action/debloquer_edition.php
+++ b/ecrire/action/debloquer_edition.php
@@ -10,13 +10,21 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action debloquer_edition
+ * 
+ * @package SPIP\Core\Edition
+ */
+ 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 /**
  * Lever les blocages d'édition pour l'utilisateur courant
+ *
+ * @uses debloquer_tous()
+ * @uses debloquer_edition()
  * 
- * @global array $GLOBALS['visiteur_session']
- * @link http://doc.spip.org/@action_instituer_collaboration_dist
+ * @global array visiteur_session
  * @return void
  */
 function action_debloquer_edition_dist() {
diff --git a/ecrire/action/desinstaller_plugin.php b/ecrire/action/desinstaller_plugin.php
index eccc6c46de7309a650ee47ac92759e90135a37ec..343564f46f91c4f3320ddb1b63d5a4a562343022 100644
--- a/ecrire/action/desinstaller_plugin.php
+++ b/ecrire/action/desinstaller_plugin.php
@@ -10,9 +10,24 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action desinstaller_plugin
+ * 
+ * @package SPIP\Core\Plugins
+ */
+ 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
-// http://doc.spip.org/@action_desinstaller_plugin_dist
+/**
+ * Action de désinstallation d'un plugin
+ *
+ * L'argument attendu est le préfixe du plugin à désinstaller.
+ * 
+ * @uses plugins_installer_dist()
+ * 
+ * @global array visiteur_session
+ * @return void
+ */
 function action_desinstaller_plugin_dist() {
 
 	$securiser_action = charger_fonction('securiser_action', 'inc');
diff --git a/ecrire/action/editer_article.php b/ecrire/action/editer_article.php
index 980514562b6dde113ccdcf2d311fa20584afd03b..d7b27b0c14414ea22feaa311dfb1bec50cd8f69d 100644
--- a/ecrire/action/editer_article.php
+++ b/ecrire/action/editer_article.php
@@ -28,6 +28,8 @@ if (!defined('_ECRIRE_INC_VERSION')) return;
  * (avec _request())
  * 
  * @link http://doc.spip.org/@action_editer_article_dist
+ * @uses article_inserer()
+ * @uses article_modifier()
  * 
  * @param null|int $arg
  *     Identifiant de l'article. En absence utilise l'argument
@@ -74,11 +76,12 @@ function action_editer_article_dist($arg=null) {
  * @param array|null $set
  *     Couples (colonne => valeur) de données à modifier.
  *     En leur absence, on cherche les données dans les champs éditables
- *     qui ont été postés (via _request())
+ *     qui ont été postés (via collecter_requests())
  * @return string|null
- *     Chaîne vide si aucune erreur,
- *     Null si aucun champ à modifier,
- *     Chaîne contenant un texte d'erreur sinon.
+ *
+ *     - Chaîne vide si aucune erreur,
+ *     - Null si aucun champ à modifier,
+ *     - Chaîne contenant un texte d'erreur sinon.
  */
 function article_modifier($id_article, $set=null) {
 
@@ -125,6 +128,7 @@ function article_modifier($id_article, $set=null) {
  * Insérer un nouvel article en base de données
  * 
  * En plus des données enregistrées par défaut, la fonction :
+ * 
  * - retrouve un identifiant de rubrique pour stocker l'article (la
  *   première rubrique racine) si l'identifiant de rubrique transmis est
  *   nul.
@@ -140,9 +144,9 @@ function article_modifier($id_article, $set=null) {
  * @pipeline_appel pre_insertion
  * @pipeline_appel post_insertion
  *
- * @global array $GLOBALS['meta']
- * @global array $GLOBALS['visiteur_session']
- * @global string $GLOBALS['spip_lang']
+ * @global array meta
+ * @global array visiteur_session
+ * @global string spip_lang
  * 
  * @param int $id_rubrique
  *     Identifiant de la rubrique parente
@@ -232,8 +236,8 @@ function article_inserer($id_rubrique) {
  * 
  * @global array $GLOBALS['meta'] 
  *
- * @pipeline_appel pre_insertion
- * @pipeline_appel post_insertion
+ * @pipeline_appel pre_edition
+ * @pipeline_appel post_edition
  * 
  * @param int $id_article
  *     Identifiant de l'article
diff --git a/ecrire/action/editer_auteur.php b/ecrire/action/editer_auteur.php
index 6ad64ade94c9daeeaff967a473e557e859975422..d3bfc09649268694d2ae372b94a3217c61eb5e08 100644
--- a/ecrire/action/editer_auteur.php
+++ b/ecrire/action/editer_auteur.php
@@ -10,15 +10,28 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action editer_article et de l'API d'édition d'un article
+ * 
+ * @package SPIP\Core\Auteurs\Edition
+ */
+ 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 /**
- * Editer ou créer un auteur
+ * Éditer ou créer un auteur
+ *
+ * Si aucun identifiant d'auteur n'est donné, on crée alors un nouvel auteur.
  * 
- * @link http://doc.spip.org/@action_editer_auteur_dist
- * @global array $GLOBALS['visiteur_session']
- * @param array $arg 
- * @return array 
+ * @global array visiteur_session
+ * @uses auteur_inserer()
+ * @uses auteur_modifier()
+ * 
+ * @param array|null $arg
+ *     Identifiant de l'auteur. En absence utilise l'argument
+ *     de l'action sécurisée.
+ * @return array
+ *     Liste (identifiant de l'auteur, Texte d'erreur éventuel)
  */
 function action_editer_auteur_dist($arg=null) {
 
@@ -57,10 +70,15 @@ function action_editer_auteur_dist($arg=null) {
 }
 
 /**
- * Inserer un auteur en base
+ * Insérer un auteur en base
+ *
+ * @pipeline_appel pre_insertion
+ * @pipeline_appel post_insertion
  * 
- * @param string $source
+ * @param string|null $source
+ *     D'où provient l'auteur créé ? par défaut 'spip', mais peut être 'ldap' ou autre.
  * @return int
+ *     Identifiant de l'auteur créé
  */
 function auteur_inserer($source=null) {
 
@@ -96,14 +114,23 @@ function auteur_inserer($source=null) {
 
 
 /**
+ * Modifier un auteur
+ * 
  * Appelle toutes les fonctions de modification d'un auteur
  *
  * @param int $id_auteur
- * @param array $set
+ *     Identifiant de l'auteur
+ * @param array|null $set
+ *     Couples (colonne => valeur) de données à modifier.
+ *     En leur absence, on cherche les données dans les champs éditables
+ *     qui ont été postés (via collecter_requests())
  * @param bool $force_update
- *   permet de forcer la maj en base des champs fournis, sans passer par instancier
- *   utilise par auth/spip
- * @return string
+ *   Permet de forcer la maj en base des champs fournis, sans passer par instancier.
+ *   Utilise par auth/spip
+ * @return string|null
+ *
+ *     - Chaîne vide si aucune erreur,
+ *     - Chaîne contenant un texte d'erreur sinon.
  */
 function auteur_modifier($id_auteur, $set = null, $force_update=false) {
 
@@ -158,17 +185,20 @@ function auteur_modifier($id_auteur, $set = null, $force_update=false) {
 }
 
 /**
- * Associer un auteur a des objets listes sous forme
- * array($objet=>$id_objets,...)
- * $id_objets peut lui meme etre un scalaire ou un tableau pour une liste d'objets du meme type.
- *
- * On peut passer optionnellement une qualification du (des) lien(s) qui sera
- * alors appliquee dans la foulee.
- * En cas de lot de liens, c'est la meme qualification qui est appliquee a tous
+ * Associer un auteur à des objets listés
  *
+ * @uses objet_associer()
+ * 
  * @param int $id_auteur
+ *     Identifiant de l'auteur
  * @param array $objets
- * @param array $qualif
+ *     Liste sous la forme `array($objet=>$id_objets,...)`. 
+ *     `$id_objets` peut lui-même être un scalaire ou un tableau pour une liste
+ *     d'objets du même type.
+ * @param array|null $qualif
+ *     Optionnellement indique une qualification du (des) lien(s) qui sera
+ *     alors appliquée dans la foulée.
+ *     En cas de lot de liens, c'est la même qualification qui est appliquée à tous
  * @return string
  */
 function auteur_associer($id_auteur,$objets, $qualif = null){
@@ -178,7 +208,10 @@ function auteur_associer($id_auteur,$objets, $qualif = null){
 
 
 /**
- * Ancien nommage pour compatibilite
+ * Ancien nommage pour compatibilité
+ *
+ * @deprecated Utiliser auteur_associer()
+ * @see auteur_associer()
  * 
  * @param int $id_auteur
  * @param array $c
@@ -189,14 +222,18 @@ function auteur_referent($id_auteur,$c){
 }
 
 /**
- * Dissocier un auteur des objets listes sous forme
- * array($objet=>$id_objets,...)
- * $id_objets peut lui meme etre un scalaire ou un tableau pour une liste d'objets du meme type
- *
- * un * pour $id_auteur,$objet,$id_objet permet de traiter par lot
+ * Dissocier un auteur des objets listés
  *
+ * @uses objet_dissocier()
+ * 
  * @param int $id_auteur
+ *     Identifiant de l'auteur
  * @param array $objets
+ *     Liste sous la forme `array($objet=>$id_objets,...)`. 
+ *     `$id_objets` peut lui-même être un scalaire ou un tableau pour une liste
+ *     d'objets du même type.
+ *
+ *     Un `*` pour $id_auteur,$objet,$id_objet permet de traiter par lot
  * @return string
  */
 function auteur_dissocier($id_auteur,$objets){
@@ -205,17 +242,20 @@ function auteur_dissocier($id_auteur,$objets){
 }
 
 /**
- * Qualifier le lien d'un auteur avec les objets listes
- * array($objet=>$id_objets,...)
- * $id_objets peut lui meme etre un scalaire ou un tableau pour une liste d'objets du meme type
+ * Qualifier le lien d'un auteur avec les objets listés
+ * 
+ * @uses objet_qualifier_liens()
  * 
- * exemple :
- * $c = array('vu'=>'oui');
- * un * pour $id_auteur,$objet,$id_objet permet de traiter par lot
- *
  * @param int $id_auteur
+ *     Identifiant de l'auteur
  * @param array $objets
+ *     Liste sous la forme `array($objet=>$id_objets,...)`. 
+ *     `$id_objets` peut lui-même être un scalaire ou un tableau pour une liste
+ *     d'objets du même type.
+ *
+ *     Un `*` pour $id_auteur,$objet,$id_objet permet de traiter par lot
  * @param array $qualif
+ *     Couples (colonne, valeur) tel que `array('vu'=>'oui');`
  * @return bool|int
  */
 function auteur_qualifier($id_auteur,$objets,$qualif){
@@ -226,11 +266,16 @@ function auteur_qualifier($id_auteur,$objets,$qualif){
 
 /**
  * Modifier le statut d'un auteur, ou son login/pass
+ *
+ * @pipeline_appel pre_edition
+ * @pipeline_appel post_edition
  * 
- * @link http://doc.spip.org/@instituer_auteur
- * @param  $id_auteur
- * @param  $c
+ * @param int $id_auteur
+ *     Identifiant de l'auteur
+ * @param array $c
+ *     Couples (colonne => valeur) des données à instituer
  * @param bool $force_webmestre
+ *     Autoriser un auteur à passer webmestre (force l'autorisation)
  * @return bool|string
  */
 function auteur_instituer($id_auteur, $c, $force_webmestre = false) {
@@ -346,18 +391,62 @@ function auteur_instituer($id_auteur, $c, $force_webmestre = false) {
 }
 
 
+// Fonctions Dépréciées
+// --------------------
 
 
+/**
+ * Insertion d'un auteur
+ *
+ * @deprecated Utiliser auteur_inserer()
+ * @see auteur_inserer()
+ * 
+ * @param string|null $source
+ * @return int
+ */
 function insert_auteur($source=null) {
 	return auteur_inserer($source);
 }
+
+/**
+ * Modification d'un auteur
+ *
+ * @deprecated Utiliser auteur_modifier()
+ * @see auteur_modifier()
+ * 
+ * @param int $id_auteur
+ * @param array|null $set
+ * @return string|null
+ */
 function auteurs_set($id_auteur, $set = null) {
 	return auteur_modifier($id_auteur,$set);
 }
+
+/**
+ * Modifier le statut d'un auteur, ou son login/pass
+ *
+ * @deprecated Utiliser auteur_instituer()
+ * @see auteur_instituer()
+ * 
+ * @param int $id_auteur
+ * @param array $c
+ * @param bool $force_webmestre
+ * @return bool|string
+ */
 function instituer_auteur($id_auteur, $c, $force_webmestre = false) {
 	return auteur_instituer($id_auteur,$c,$force_webmestre);
 }
-// http://doc.spip.org/@revision_auteur
+
+/**
+ * Créer une révision d'un auteur
+ *
+ * @deprecated Utiliser auteur_modifier()
+ * @see auteur_modifier()
+ * 
+ * @param int $id_auteur
+ * @param array $c
+ * @return string|null
+ */
 function revision_auteur($id_auteur, $c=false) {
 	return auteur_modifier($id_auteur,$c);
 }
diff --git a/ecrire/action/purger.php b/ecrire/action/purger.php
index 054b7aacf040b5e109b0b1f7510a4dee60afefae..1f6986037b592494ce9155fed0954aa0a2b553b7 100644
--- a/ecrire/action/purger.php
+++ b/ecrire/action/purger.php
@@ -10,9 +10,32 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion de l'action purger pour nettoyer le cache
+ *
+ * @package SPIP\Core\Cache
+**/
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
-// http://doc.spip.org/@action_purger_dist
+/**
+ * Action de purge du cache
+ *
+ * L'argument peut être :
+ *
+ * - inhibe_cache : inhibe le cache pendant 24h
+ * - reactive_cache : enlève l'inhibition du cache
+ * - cache : nettoie tous les caches (sauf celui des vignettes)
+ * - squelettes : nettoie le cache de compilation des squelettes
+ * - vignettes : nettoie le cache des vignettes (et compressions css/js)
+ *
+ * @pipeline_appel trig_purger
+ * @uses supprime_invalideurs()
+ * @uses purger_repertoire()
+ * 
+ * @param string|null $arg
+ *     Argument attendu. En absence utilise l'argument
+ *     de l'action sécurisée.
+ */
 function action_purger_dist($arg=null)
 {
 	if (is_null($arg)) {
diff --git a/ecrire/inc/invalideur.php b/ecrire/inc/invalideur.php
index 3ba786a39858cf6ed89cb2c495c2b0a8323b8996..444b9d66bfc8f4ec8b42947f3f48de86708aa77e 100644
--- a/ecrire/inc/invalideur.php
+++ b/ecrire/inc/invalideur.php
@@ -10,20 +10,37 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion du cache et des invalidations de cache
+ *
+ * @package SPIP\Core\Cache
+**/
 
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
 include_spip('base/serial');
 
-# estime la taille moyenne d'un fichier cache, pour ne pas les regarder (10ko)
+/** Estime la taille moyenne d'un fichier cache, pour ne pas les regarder (10ko) */
 define('_TAILLE_MOYENNE_FICHIER_CACHE', 1024 * 10);
-# si un fichier n'a pas servi (fileatime) depuis plus d'une heure, on se sent
-# en droit de l'eliminer
+/**
+ * Si un fichier n'a pas servi (fileatime) depuis plus d'une heure, on se sent
+ * en droit de l'éliminer
+ */
 define('_AGE_CACHE_ATIME', 3600);
 
-// Donne le nombre de fichiers dans un repertoire (plat, pour aller vite)
-// false si erreur
-// http://doc.spip.org/@nombre_de_fichiers_repertoire
+/**
+ * Calcul le nombre de fichiers à la racine d'un répertoire ainsi qu'une
+ * approximation de la taille du répertoire
+ *
+ * On ne calcule que la racine pour pour aller vite.
+ * 
+ * @param string $dir Chemin du répertoire
+ * @param string $nb_estim_taille Nombre de fichiers maximum pour estimer la taille
+ * @return bool|array
+ *
+ *     - false si le répertoire ne peut pas être ouvert
+ *     - array(nombre de fichiers, approximation de la taille en octet) sinon
+**/
 function nombre_de_fichiers_repertoire($dir,$nb_estim_taille = 20) {
 	$taille = 0; // mesurer la taille de N fichiers au hasard dans le repertoire
 	$nb = $nb_estim_taille;
@@ -41,9 +58,15 @@ function nombre_de_fichiers_repertoire($dir,$nb_estim_taille = 20) {
 	return array($total,$taille?$taille/($nb_estim_taille-$nb):_TAILLE_MOYENNE_FICHIER_CACHE);
 }
 
-// Indique la taille du repertoire cache ; pour de gros volumes,
-// impossible d'ouvrir chaque fichier, on y va donc a l'estime
-// http://doc.spip.org/@taille_du_cache
+
+/**
+ * Évalue approximativement la taille du cache
+ *
+ * Pour de gros volumes, impossible d'ouvrir chaque fichier,
+ * on y va donc à l'estime !
+ *
+ * @return int Taille approximative en octets
+**/
 function taille_du_cache() {
 	$total = 0;
 	$taille = 0;
@@ -57,11 +80,29 @@ function taille_du_cache() {
 	return $total * $taille / 16;
 }
 
-// Invalider les caches lies a telle condition
-// les invalideurs sont de la forme 'objet/id_objet'
-// la condition est generalement "id='objet/id_objet'"
-// ici on se contente de noter la date de mise a jour dans les metas
-// http://doc.spip.org/@suivre_invalideur
+
+/**
+ * Invalider les caches liés à telle condition
+ *
+ * Les invalideurs sont de la forme 'objet/id_objet'.
+ * La condition est géneralement "id='objet/id_objet'".
+ *
+ * Ici on se contente de noter la date de mise à jour dans les metas,
+ * pour le type d'objet en question (non utilisé cependant) et pour
+ * tout le site (sur la meta `derniere_modif`)
+ *
+ * @global derniere_modif_invalide
+ *     Par défaut à `true`, la meta `derniere_modif` est systématiquement
+ *     calculée dès qu'un invalideur se présente. Cette globale peut
+ *     être mise à `false` (aucun changement sur `derniere_modif`) ou
+ *     sur une liste de type d'objets (changements uniquement lorsqu'une
+ *     modification d'un des objets se présente).
+ *     
+ * @param string $cond
+ *     Condition d'invalidation
+ * @param bool $modif
+ *     Inutilisé
+**/
 function suivre_invalideur($cond, $modif=true) {
 	if (!$modif)
 		return;
@@ -88,12 +129,25 @@ function suivre_invalideur($cond, $modif=true) {
 
 
 
-// Utilisee pour vider le cache depuis l'espace prive
-// (ou juste les squelettes si un changement de config le necessite)
-// si $atime est passee en argument, ne pas supprimer ce qui a servi
-// plus recemment que cette date (via fileatime)
-// retourne le nombre de fichiers supprimes
-// http://doc.spip.org/@purger_repertoire
+
+/**
+ * Purge un répertoire de ses fichiers
+ *
+ * Utilisée entre autres pour vider le cache depuis l'espace privé
+ *
+ * @uses supprimer_fichier()
+ * 
+ * @param string $dir
+ *     Chemin du répertoire à purger
+ * @param array $options
+ *     Tableau des options. Peut être :
+ *
+ *     - atime : timestamp pour ne supprimer que les fichiers antérieurs
+ *       à cette date (via fileatime)
+ *     - limit : nombre maximum de suppressions
+ * @return int
+ *     Nombre de fichiers supprimés
+**/
 function purger_repertoire($dir, $options=array()) {
 	$handle = @opendir($dir);
 	if (!$handle) return;
diff --git a/ecrire/inc/utils.php b/ecrire/inc/utils.php
index 4ba178a5c8b38fe272bfcde301608b0ce4245a95..f864259634d106a9d8a0a2426dda2926ca6a0e5b 100644
--- a/ecrire/inc/utils.php
+++ b/ecrire/inc/utils.php
@@ -1444,12 +1444,12 @@ function generer_url_action($script, $args="", $no_entities=false , $public = fa
 
 
 /**
- * Fonction d'initialisation groupee pour compatibilite ascendante
+ * Fonction d'initialisation groupée pour compatibilité ascendante
  *
- * @param string $pi
- * @param string $pa
- * @param string $ti
- * @param string $ta
+ * @param string $pi Répertoire permanent inaccessible
+ * @param string $pa Répertoire permanent accessible
+ * @param string $ti Répertoire temporaire inaccessible
+ * @param string $ta Répertoire temporaire accessible
  */
 function spip_initialisation($pi=NULL, $pa=NULL, $ti=NULL, $ta=NULL) {
 	spip_initialisation_core($pi,$pa,$ti,$ta);
@@ -1457,18 +1457,20 @@ function spip_initialisation($pi=NULL, $pa=NULL, $ti=NULL, $ta=NULL) {
 }
 
 /**
- * Fonction d'initialisation, appellee dans inc_version ou mes_options
- * Elle definit les repertoires et fichiers non partageables
- * et indique dans $test_dirs ceux devant etre accessibles en ecriture
- * mais ne touche pas a cette variable si elle est deja definie
- * afin que mes_options.php puisse en specifier d'autres.
- * Elle definit ensuite les noms des fichiers et les droits.
- * Puis simule un register_global=on securise.
+ * Fonction d'initialisation, appellée dans inc_version ou mes_options
+ * 
+ * Elle définit les répertoires et fichiers non partageables
+ * et indique dans $test_dirs ceux devant être accessibles en écriture
+ * mais ne touche pas à cette variable si elle est déjà définie
+ * afin que mes_options.php puisse en spécifier d'autres.
+ * 
+ * Elle définit ensuite les noms des fichiers et les droits.
+ * Puis simule un register_global=on sécurisé.
  *
- * @param string $pi
- * @param string $pa
- * @param string $ti
- * @param string $ta
+ * @param string $pi Répertoire permanent inaccessible
+ * @param string $pa Répertoire permanent accessible
+ * @param string $ti Répertoire temporaire inaccessible
+ * @param string $ta Répertoire temporaire accessible
  */
 function spip_initialisation_core($pi=NULL, $pa=NULL, $ti=NULL, $ta=NULL) {
 	static $too_late = 0;