Made various edits to docs/ref/utils.txt.

1 files changed, 28 insertions, 23 deletions

diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 1350bd6af7..1c885fa472 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -16,10 +16,10 @@ the :ref:`internal release deprecation policy <internal-release-deprecation-poli
 .. module:: django.utils.cache
    :synopsis: Helper functions for controlling caching.
 
-This module contains helper functions for controlling caching. It does so by
-managing the ``Vary`` header of responses. It includes functions to patch the
-header of response objects directly and decorators that change functions to do
-that header-patching themselves.
+This module contains helper functions for controlling HTTP caching. It does so
+by managing the ``Vary`` header of responses. It includes functions to patch
+the header of response objects directly and decorators that change functions to
+do that header-patching themselves.
 
 For information on the ``Vary`` header, see :rfc:`7231#section-7.1.4`.
 
@@ -99,10 +99,13 @@ need to distinguish caches by the ``Accept-language`` header.
 ==========================
 
 .. module:: django.utils.dateparse
-   :synopsis: Functions to parse datetime objects.
+   :synopsis: Functions to parse strings to datetime objects.
 
 The functions defined in this module share the following properties:
 
+- They accept strings in ISO 8601 date/time formats (or some close
+  alternatives) and return objects from the corresponding classes in Python's
+  :mod:`datetime` module.
 - They raise :exc:`ValueError` if their input is well formatted but isn't a
   valid date or time.
 - They return ``None`` if it isn't well formatted at all.
@@ -199,8 +202,8 @@ The functions defined in this module share the following properties:
 
 .. function:: smart_text(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Returns a ``str`` object representing ``s``. Treats bytestrings using the
-    ``encoding`` codec.
+    Returns a ``str`` object representing arbitrary object ``s``. Treats
+    bytestrings using the ``encoding`` codec.
 
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
@@ -222,8 +225,8 @@ The functions defined in this module share the following properties:
 
 .. function:: smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Returns a bytestring version of ``s``, encoded as specified in
-    ``encoding``.
+    Returns a bytestring version of arbitrary object ``s``, encoded as
+    specified in ``encoding``.
 
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
@@ -468,7 +471,7 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
                 ...
 
     Note that as the method is now a property, in Python code it will need to
-    be invoked appropriately::
+    be accessed appropriately::
 
         # in the view:
         if person.friends:
@@ -822,25 +825,27 @@ appropriate entities.
     is translated to "persona", the regular expression will match
     ``persona/(?P<pk>\d+)/$``, e.g. ``persona/5/``.
 
-.. function:: slugify(allow_unicode=False)
+.. function:: slugify(value, allow_unicode=False)
 
-    Converts to ASCII if ``allow_unicode`` is ``False`` (default). Converts spaces to
-    hyphens. Removes characters that aren't alphanumerics, underscores, or
-    hyphens. Converts to lowercase. Also strips leading and trailing whitespace.
+    Converts a string to a URL slug by:
 
-    For example::
-
-        slugify(value)
+    #. Converting to ASCII if ``allow_unicode`` is ``False`` (the default).
+    #. Removing characters that aren't alphanumerics, underscores, hyphens, or
+       whitespace.
+    #. Removing leading and trailing whitespace.
+    #. Converting to lowercase.
+    #. Replacing any whitespace or repeated dashes with single dashes.
 
-    If ``value`` is ``"Joel is a slug"``, the output will be
-    ``"joel-is-a-slug"``.
+    For example::
 
-    You can set the ``allow_unicode`` parameter to ``True``, if you want to
-    allow Unicode characters::
+        >>> slugify(' Joel is a slug ')
+        'joel-is-a-slug'
 
-        slugify(value, allow_unicode=True)
+    If you want to allow Unicode characters, pass ``allow_unicode=True``. For
+    example::
 
-    If ``value`` is ``"你好 World"``, the output will be ``"你好-world"``.
+        >>> slugify('你好 World', allow_unicode=True)
+        '你好-world'
 
 .. _time-zone-selection-functions: