From f33e15036907d6e4bda6116dc84097e9e590d2c8 Mon Sep 17 00:00:00 2001
From: Luke Plant <L.Plant.98@cantab.net>
Date: Sat, 30 Jun 2012 16:41:51 +0100
Subject: [PATCH] Documented utils.html.escape and conditional_escape

---
 django/utils/html.py | 14 +++++++-------
 docs/ref/utils.txt   | 22 ++++++++++++++++++++++
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/django/utils/html.py b/django/utils/html.py
index 014d837bbb..fe2e6b7a29 100644
--- a/django/utils/html.py
+++ b/django/utils/html.py
@@ -31,11 +31,11 @@ hard_coded_bullets_re = re.compile(r'((?:<p>(?:%s).*?[a-zA-Z].*?</p>\s*)+)' % '|
 trailing_empty_content_re = re.compile(r'(?:<p>(?:&nbsp;|\s|<br \/>)*?</p>\s*)+\Z')
 del x # Temporary variable
 
-def escape(html):
+def escape(text):
     """
-    Returns the given HTML with ampersands, quotes and angle brackets encoded.
+    Returns the given text with ampersands, quotes and angle brackets encoded for use in HTML.
     """
-    return mark_safe(force_unicode(html).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))
+    return mark_safe(force_unicode(text).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))
 escape = allow_lazy(escape, unicode)
 
 _base_js_escapes = (
@@ -63,14 +63,14 @@ def escapejs(value):
     return value
 escapejs = allow_lazy(escapejs, unicode)
 
-def conditional_escape(html):
+def conditional_escape(text):
     """
     Similar to escape(), except that it doesn't operate on pre-escaped strings.
     """
-    if isinstance(html, SafeData):
-        return html
+    if isinstance(text, SafeData):
+        return text
     else:
-        return escape(html)
+        return escape(text)
 
 def linebreaks(value, autoescape=False):
     """Converts newlines into <p> and <br />s."""
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 0974409453..549812296b 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -387,6 +387,28 @@ Atom1Feed
     input is a proper string, then add support for lazy translation objects at the
     end.
 
+``django.utils.html``
+=====================
+
+.. module:: django.utils.html
+   :synopsis: HTML helper functions
+
+Usually you should build up HTML using Django's templates to make use of its
+autoescape mechanism, using the utilities in :mod:`django.utils.safestring`
+where appropriate. This module provides some additional low level utilitiesfor
+escaping HTML.
+
+.. function:: escape(text)
+
+    Returns the given text with ampersands, quotes and angle brackets encoded
+    for use in HTML. The input is first passed through
+    :func:`~django.utils.encoding.force_unicode` and the output has
+    :func:`~django.utils.safestring.mark_safe` applied.
+
+.. function:: conditional_escape(text)
+
+    Similar to ``escape()``, except that it doesn't operate on pre-escaped strings,
+    so it will not double escape.
 
 ``django.utils.http``
 =====================