whatsnew: filecmp.clear_cache, and reword description of cache in docs.

Doc/library/filecmp.rst

@@ -28,8 +28,8 @@ The :mod:`filecmp` module defines the following functions:
    portability and efficiency.
 
    This function uses a cache for past comparisons and the results,
-   with a cache invalidation mechanism relying on stale signatures
-   or by explicitly calling :func:`clear_cache`.
+   with cache entries invalidated if the :func:`os.stat` information for the
+   file changes.  The entire cache may be cleared using :func:`clear_cache`.
 
 
 .. function:: cmpfiles(dir1, dir2, common, shallow=True)
@@ -54,12 +54,12 @@ The :mod:`filecmp` module defines the following functions:
 
 .. function:: clear_cache()
 
-   .. versionadded:: 3.4
-
    Clear the filecmp cache. This may be useful if a file is compared so quickly
    after it is modified that it is within the mtime resolution of
    the underlying filesystem.
 
+   .. versionadded:: 3.4
+
 
 .. _dircmp-objects:
 

Doc/whatsnew/3.4.rst

@@ -675,6 +675,17 @@ handling).
 (Contributed by R. David Murray in :issue:`18891`.)
 
 
+filecmp
+-------
+
+A new :func:`~filecmp.clear_cache` function provides the ability to clear the
+:mod:`filecmp` comparison cache, which uses :func:`os.stat` information to
+determine if the file has changed since the last compare.  This can be used,
+for example, if the file might have been changed and re-checked in less time
+than the resolution of a particular filesystem's file modification time field.
+(Contributed by Mark Levitt in :issue:`18149`.)
+
+
 functools
 ---------
 

Lib/filecmp.py

@@ -43,8 +43,8 @@ def cmp(f1, f2, shallow=True):
     True if the files are the same, False otherwise.
 
     This function uses a cache for past comparisons and the results,
-    with a cache invalidation mechanism relying on stale signatures
-    or by explicitly calling clear_cache().
+    with cache entries invalidated if their stat information
+    changes.  The cache may be cleared by calling clear_cache().
 
     """