From 9c24949719fdfec33d660698b4b38f2725e7374a Mon Sep 17 00:00:00 2001
From: Matthieu Marcillaud <marcimat@rezo.net>
Date: Thu, 14 Feb 2013 10:52:15 +0000
Subject: [PATCH] =?UTF-8?q?PHPdoc=20sur=20les=20balises=20d=C3=A9but=5Fsur?=
 =?UTF-8?q?ligne=20et=20fin=5Fsurligne.=20On=20pourrait=20les=20supprimer?=
 =?UTF-8?q?=20:=20elles=20n'ont=20plus=20aucun=20effet=20depuis=20r9343?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ecrire/inc/surligne.php   | 34 +++++++++++++++++++++++++++++----
 ecrire/public/balises.php | 40 +++++++++++++++++++++++++++++++++------
 2 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/ecrire/inc/surligne.php b/ecrire/inc/surligne.php
index 0ce32c0b1e..68c355d7be 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 2dc95dedf2..06d6a702ae 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 . "-->'";
-- 
GitLab