Neaten-up a bit.

Doc/library/functools.rst

@@ -72,10 +72,10 @@ The :mod:`functools` module defines the following functions:
 
    A `LRU (least recently used) cache
    <http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used>`_
-   is indicated when the pattern of calls changes over time, such as
-   when more recent calls are the best predictors of upcoming calls
+   works best when more recent calls are the best predictors of upcoming calls
    (for example, the most popular articles on a news server tend to
-   change every day).
+   change each day).  The cache's size limit assurs that caching does not
+   grow without bound on long-running processes such as web servers.
 
    .. versionadded:: 3.2
 

Doc/whatsnew/3.2.rst

@@ -332,15 +332,13 @@ New, Improved, and Deprecated Modules
          c.execute('SELECT phonenumber FROM phonelist WHERE name=?', (name,))
          return c.fetchone()[0]
 
-  XXX: update for Issue 10586 changes to cache statistics API
-
   To help with choosing an effective cache size, the wrapped function is
-  instrumented with two attributes *cache_hits* and *cache_misses*:
+  instrumented with info function:
 
   >>> for name in user_requests:
   ...     get_phone_number(name)
-  >>> print(get_phone_number.cache_hits, get_phone_number.cache_misses)
-  4805 980
+  >>> get_phone_number.cache_info()
+  CacheInfo(maxsize=300, size=300, hits=4805, misses=980)
 
   If the phonelist table gets updated, the outdated contents of the cache can be
   cleared with:

Lib/functools.py

@@ -121,10 +121,9 @@ def lru_cache(maxsize=100):
 
     Arguments to the cached function must be hashable.
 
-    Significant statistics (maxsize, size, hits, misses) are
-      available through the f.cache_info() named tuple.
-    Clear the cache and statistics using f.cache_clear().
-    The underlying function is stored in f.__wrapped__.
+    View the cache statistics named tuple (maxsize, size, hits, misses) with
+    f.cache_info().  Clear the cache and statistics with f.cache_clear().
+    And access the underlying function with f.__wrapped__.
 
     See:  http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used
 
@@ -141,7 +140,7 @@ def lru_cache(maxsize=100):
         cache_popitem = cache.popitem
         cache_renew = cache.move_to_end
         hits = misses = 0
-        kwd_mark = object()             # separate positional and keyword args
+        kwd_mark = object()             # separates positional and keyword args
         lock = Lock()
 
         @wraps(user_function)
@@ -165,7 +164,7 @@ def lru_cache(maxsize=100):
             return result
 
         def cache_info():
-            """Report significant cache statistics"""
+            """Report cache statistics"""
             with lock:
                 return _CacheInfo(maxsize, len(cache), hits, misses)