From cf3faedc8071bfd60f343df45333766c2e059057 Mon Sep 17 00:00:00 2001
From: Matthieu Marcillaud <marcimat@rezo.net>
Date: Sun, 12 Oct 2014 16:34:21 +0000
Subject: [PATCH] PHPdoc de la fonction/filtre texte_script

---
 ecrire/inc/utils.php | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/ecrire/inc/utils.php b/ecrire/inc/utils.php
index 97094a466d..d4c274abef 100644
--- a/ecrire/inc/utils.php
+++ b/ecrire/inc/utils.php
@@ -964,10 +964,37 @@ function http_script($script, $src='', $noscript='') {
 	: '';
 }
 
-// Transforme n'importe quel champ en une chaine utilisable
-// en PHP ou Javascript en toute securite
-// < ? php $x = '[(#TEXTE|texte_script)]'; ? >
-// http://doc.spip.org/@texte_script
+
+/**
+ * Sécurise du texte à écrire dans du PHP ou du Javascript.
+ * 
+ * Transforme n'importe quel texte en une chaîne utilisable
+ * en PHP ou Javascript en toute sécurité, à l'intérieur d'apostrophes
+ * simples (`'` uniquement ; pas `"`)
+ *
+ * Utile particulièrement en filtre dans un squelettes
+ * pour écrire un contenu dans une variable JS ou PHP.
+ *
+ * Échappe les apostrophes (') du contenu transmis.
+ *
+ * @link http://www.spip.net/4281
+ * @example
+ *     PHP dans un squelette
+ *     ```
+ *     $x = '[(#TEXTE|texte_script)]';
+ *     ```
+ *
+ *     JS dans un squelette (transmettre une chaîne de langue)
+ *     ```
+ *     $x = '<:afficher_calendrier|texte_script:>';
+ *     ```
+ *
+ * @filtre
+ * @param string $texte
+ *     Texte à échapper
+ * @return string
+ *     Texte échappé
+**/
 function texte_script($texte) {
 	return str_replace('\'', '\\\'', str_replace('\\', '\\\\', $texte));
 }
-- 
GitLab