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

3 files changed, 17 insertions, 6 deletions

diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
index 8471a72..06d3f21 100644
--- a/Doc/library/filecmp.rst
+++ b/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:
 
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 2292297..4417f74 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/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
 ---------
 
diff --git a/Lib/filecmp.py b/Lib/filecmp.py
index 3285288..dd5a2af 100644
--- a/Lib/filecmp.py
+++ b/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().
 
     """