Fixed #24035 -- Clarified docs on CACHE_MIDDLEWARE_KEY_PREFIX vs KEY_PREFIX

docs/ref/settings.txt

@@ -283,7 +283,8 @@ CACHE_MIDDLEWARE_ALIAS
 
 Default: ``default``
 
-The cache connection to use for the cache middleware.
+The cache connection to use for the :ref:`cache middleware
+<the-per-site-cache>`.
 
 .. setting:: CACHE_MIDDLEWARE_KEY_PREFIX
 
@@ -292,7 +293,9 @@ CACHE_MIDDLEWARE_KEY_PREFIX
 
 Default: ``''`` (Empty string)
 
-The cache key prefix that the cache middleware should use.
+A string which will be prefixed to the cache keys generated by the :ref:`cache
+middleware <the-per-site-cache>`. This prefix is combined with the
+:setting:`KEY_PREFIX <CACHES-KEY_PREFIX>` setting; it does not replace it.
 
 See :doc:`/topics/cache`.
 
@@ -303,8 +306,8 @@ CACHE_MIDDLEWARE_SECONDS
 
 Default: ``600``
 
-The default number of seconds to cache a page when the caching middleware or
-``cache_page()`` decorator is used.
+The default number of seconds to cache a page for the :ref:`cache middleware
+<the-per-site-cache>`.
 
 See :doc:`/topics/cache`.
 

docs/topics/cache.txt

@@ -436,6 +436,8 @@ of 60 seconds, and a maximum capacity of 1000 items::
 Invalid arguments are silently ignored, as are invalid values of known
 arguments.
 
+.. _the-per-site-cache:
+
 The per-site cache
 ==================
 
@@ -562,9 +564,9 @@ setting for the middleware.  It can be used like this::
     def my_view(request):
         ...
 
-The two settings can also be combined. If you specify a ``cache`` *and*
-a ``key_prefix``, you will get all the settings of the requested cache
-alias, but with the key_prefix overridden.
+The ``key_prefix and ``cache`` arguments may be specified together. The
+``key_prefix`` argument and the :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`
+specified under :setting:`CACHES` will be concatenated.
 
 Specifying per-view cache in the URLconf
 ----------------------------------------