diff --git a/ecrire/inc/surligne.php b/ecrire/inc/surligne.php
index 0ce32c0b1e482c50a1b67663a1eb3aeab5250135..68c355d7be03ebc58f764297393de287cffda7db 100644
--- a/ecrire/inc/surligne.php
+++ b/ecrire/inc/surligne.php
@@ -10,16 +10,42 @@
  *  Pour plus de details voir le fichier COPYING.txt ou l'aide en ligne.   *
 \***************************************************************************/
 
+/**
+ * Gestion du surlignage des mots d'une recherche
+ *
+ * @package SPIP\Core\Surligne
+**/
 if (!defined('_ECRIRE_INC_VERSION')) return;
 
-// Ces commentaires vont etre substitue's en mode recherche
-// voir balise_DEBUT_SURLIGNE et balise_FIN_SURLIGNE
-
+/**
+ * Ancien marqueur de début de surlignement
+ * @see balise_DEBUT_SURLIGNE_dist()
+ * @deprecated N'a plus d'effet
+**/
 define('MARQUEUR_SURLIGNE', 'debut_surligneconditionnel');
+/**
+ * Ancien marqueur de fin de surlignement
+ * @see balise_FIN_SURLIGNE_dist()
+ * @deprecated N'a plus d'effet
+**/
 define('MARQUEUR_FSURLIGNE', 'finde_surligneconditionnel');
 
 
-// http://doc.spip.org/@surligner_mots
+/**
+ * Ajoute au HTML un script JS surlignant une recherche indiquée et/ou issue des réferers
+ *
+ * Ajoute à la page HTML, seulement si des mots de recherches sont présents,
+ * — soit transmis, soit dans un réferer de moteur de recherche —
+ * un script qui s'occupera de les surligner. Le script est placé dans
+ * le head HTML si le texte en possède un, sinon à la fin.
+ *
+ * @param string $page
+ *     Page HTML
+ * @param string $surcharge_surligne
+ *     Mots à surligner transmis
+ * @return string
+ *     Page HTML
+**/
 function surligner_mots($page, $surcharge_surligne = '') {
 	$surlignejs_engines = array(
 		array(",".str_replace(array("/", "."), array("\/", "\."), $GLOBALS['meta']['adresse_site']).",i", ",recherche=([^&]+),i"), //SPIP
diff --git a/ecrire/public/balises.php b/ecrire/public/balises.php
index 2dc95dedf22d4099b2ff4a53148afe5e33cf87d5..06d6a702aedb778cef4cb03509d06bf3a698cce0 100644
--- a/ecrire/public/balises.php
+++ b/ecrire/public/balises.php
@@ -481,18 +481,46 @@ function calculer_balise_expose($p, $on, $off)
 }
 
 
-// Debut et fin de surlignage auto des mots de la recherche
-// on insere une balise Span avec une classe sans spec:
-// c'est transparent s'il n'y a pas de recherche,
-// sinon elles seront remplacees par les fontions de inc_surligne
 
-// http://doc.spip.org/@balise_DEBUT_SURLIGNE_dist
+/**
+ * Compile la balise `#DEBUT_SURLIGNE` qui permettait le surlignage
+ * des mots d'une recherche
+ *
+ * @note
+ *     Cette balise n'a plus d'effet depuis r9343
+ * 
+ * @balise DEBUT_SURLIGNE
+ * @see balise_FIN_SURLIGNE_dist()
+ * @deprecated Utiliser les classes CSS `surlignable` ou `pas_surlignable`
+ *
+ * @param Champ $p
+ *     Pile au niveau de la balise
+ * @return Champ
+ *     Pile complétée par le code à générer
+**/
 function balise_DEBUT_SURLIGNE_dist($p) {
 	include_spip('inc/surligne');
 	$p->code = "'<!-- " . MARQUEUR_SURLIGNE . " -->'";
 	return $p;
 }
-// http://doc.spip.org/@balise_FIN_SURLIGNE_dist
+
+
+/**
+ * Compile la balise `#FIN_SURLIGNE` qui arrêtait le surlignage
+ * des mots d'une recherche
+ *
+ * @note
+ *     Cette balise n'a plus d'effet depuis r9343
+ * 
+ * @balise FIN_SURLIGNE
+ * @see balise_DEBUT_SURLIGNE_dist()
+ * @deprecated Utiliser les classes CSS `surlignable` ou `pas_surlignable`
+ *
+ * @param Champ $p
+ *     Pile au niveau de la balise
+ * @return Champ
+ *     Pile complétée par le code à générer
+**/
 function balise_FIN_SURLIGNE_dist($p) {
 	include_spip('inc/surligne');
 	$p->code = "'<!-- " . MARQUEUR_FSURLIGNE . "-->'";