1 files changed, 42 insertions, 2 deletions
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 50b4be95b9..1730ef6294 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -403,6 +403,10 @@ behavior. These arguments are provided as additional keys in the
     On some backends (``database`` in particular) this makes culling *much*
     faster at the expense of more cache misses.
 
+  Memcached backends pass the contents of :setting:`OPTIONS <CACHES-OPTIONS>`
+  as keyword arguments to the client constructors, allowing for more advanced
+  control of client behavior. For example usage, see below.
+
 * :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`: A string that will be
   automatically included (prepended by default) to all cache keys
   used by the Django server.
@@ -437,8 +441,44 @@ of 60 seconds, and a maximum capacity of 1000 items::
         }
     }
 
-Invalid arguments are silently ignored, as are invalid values of known
-arguments.
+Here's an example configuration for a ``python-memcached`` based backend with
+an object size limit of 2MB::
+
+    CACHES = {
+        'default': {
+            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
+            'LOCATION': '127.0.0.1:11211',
+            'OPTIONS': {
+                'server_max_value_length': 1024 * 1024 * 2,
+            }
+        }
+    }
+
+Here's an example configuration for a ``pylibmc`` based backend that enables
+the binary protocol, SASL authentication, and the ``ketama`` behavior mode::
+
+    CACHES = {
+        'default': {
+            'BACKEND': 'django.core.cache.backends.memcached.PyLibMCCache',
+            'LOCATION': '127.0.0.1:11211',
+            'OPTIONS': {
+                'binary': True,
+                'username': 'user',
+                'password': 'pass',
+                'behaviors': {
+                    'ketama': True,
+                }
+            }
+        }
+    }
+
+.. versionchanged:: 1.11
+
+    Memcached backends can now be configured using ``OPTIONS``.
+
+    In older versions, you could pass ``pylibmc`` behavior settings directly
+    inside ``OPTIONS``. This is deprecated in favor of setting them under a
+    ``behaviors`` key within ``OPTIONS`` instead.
 
 .. _the-per-site-cache: