fix up some doc issues and add test coverage

5 files changed, 55 insertions, 21 deletions

diff --git a/SCons/CacheDir.py b/SCons/CacheDir.py
index 63fac8e..79236ad 100644
--- a/SCons/CacheDir.py
+++ b/SCons/CacheDir.py
@@ -216,13 +216,10 @@ class CacheDir:
 
     @classmethod
     def copy_from_cache(cls, env, src, dst):
-        try:
-            if env.cache_timestamp_newer:
-                return env.fs.copy(src, dst)
-            else:
-                return env.fs.copy2(src, dst)
-        except AttributeError as ex:
-            raise EnvironmentError from ex
+        if env.cache_timestamp_newer:
+            return env.fs.copy(src, dst)
+        else:
+            return env.fs.copy2(src, dst)
 
     @classmethod
     def copy_to_cache(cls, env, src, dst):
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 754b59f..945ed9c 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -756,7 +756,7 @@ until after the Builder object is actually called.
 
 <scons_function name="CacheDir">
 <arguments>
-(cache_dir, custom_class=<constant>None</constant>)
+(cache_dir, custom_class=None)
 </arguments>
 <summary>
 <para>
@@ -772,10 +772,15 @@ Specifying a
 of
 <constant>None</constant>
 disables derived file caching.
-A custom class which is a subclass of
-<classname>SCons.CacheDir.CacheDir<classname>
-can be passed as the optional second parameter
-allowing customization of the caching behaviors.
+</para>
+
+<para>
+When specifying a
+<parameter>custom_class</parameter> which should be a class type which is a subclass of
+<classname>SCons.CacheDir.CacheDir</classname>, SCons will
+internally invoke this class to use for performing caching operations.
+This argument is optional and if left to default <constant>None</constant>, will use the
+default <classname>SCons.CacheDir.CacheDir</classname> class.
 </para>
 
 <para>
diff --git a/SCons/EnvironmentTests.py b/SCons/EnvironmentTests.py
index 88577ba..a04c544 100644
--- a/SCons/EnvironmentTests.py
+++ b/SCons/EnvironmentTests.py
@@ -1450,6 +1450,30 @@ def exists(env):
         assert env['TOOL2'] == 222, env
         assert env['XYZ'] == 'ddd', env
 
+    def test_default_copy_cache(self):
+        copied = False
+        def copy2(self, src, dst):
+            nonlocal copied
+            copied = True
+
+        save_copy_from_cache = SCons.CacheDir.CacheDir.copy_from_cache
+        SCons.CacheDir.CacheDir.copy_from_cache = copy2
+
+        save_copy_to_cache = SCons.CacheDir.CacheDir.copy_to_cache
+        SCons.CacheDir.CacheDir.copy_to_cache = copy2
+
+        env = self.TestEnvironment()
+
+        SCons.Environment.default_copy_from_cache(env, 'test.in', 'test.out')
+        assert copied
+
+        copied = False
+        SCons.Environment.default_copy_to_cache(env, 'test.in', 'test.out')
+        assert copied
+
+        SCons.CacheDir.CacheDir.copy_from_cache = save_copy_from_cache
+        SCons.CacheDir.CacheDir.copy_to_cache = save_copy_to_cache
+
     def test_concat(self):
         """Test _concat()"""
         e1 = self.TestEnvironment(PRE='pre', SUF='suf', STR='a b', LIST=['a', 'b'])
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index eff4388..4425545 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -512,20 +512,22 @@ Program('prog',
   </section>
 
   <section>
-    <title>Using a Custom CacheDir class</title>
+    <title>Using a Custom CacheDir Class</title>
 
     <para>
 
-    SCons internal <classname>CacheDir</classname> class can be extended to support customization
+    SCon's internal <classname>CacheDir</classname> class can be extended to support customization
     around the details of caching behaviors, for example using compressed cache files,
-    encrypted cache files, gathering statistics and data or many other aspects.
+    encrypted cache files, gathering statistics and data, or many other aspects.
 
     </para>
 
     <para>
 
-    To create a custom &f-link-CacheDir; class, your custom class must be a subclass of SCons internal <classname>SCons.CacheDir.CacheDir</classname> class.
-    You can then pass your custom &f-link-CacheDir; class to the CacheDir call or set the environment construction variable &cv-link-CACHEDIR_CLASS; before configuring the cache
+    To create your own custom &f-link-CacheDir; class, your custom class must be a subclass
+    of SCons internal <classname>SCons.CacheDir.CacheDir</classname> class.
+    You can then pass your custom &f-link-CacheDir; class to the &f-link-CacheDir;
+    method or set the environment construction variable &cv-link-CACHEDIR_CLASS; to the class before configuring the cache
     in that environment. SCons will internally invoke and use your custom class when performing
     cache operations. The below example shows a simple use case of overriding the copy_from_cache
     method to record the total number of bytes pulled from the cache.
@@ -536,6 +538,7 @@ Program('prog',
       <file name="SConstruct" printme="1">
         import SCons
         import os
+
         class CustomCacheDir(SCons.CacheDir.CacheDir):
             total_retrieved = 0
 
@@ -547,7 +550,7 @@ Program('prog',
 
         env = Environment()
         env.CacheDir('scons-cache', CustomCacheDir)
-        ...
+        # ...
       </file>
     </scons_example>
 
diff --git a/test/CacheDir/CACHEDIR_CLASS.py b/test/CacheDir/CACHEDIR_CLASS.py
index 2846b28..ef34605 100644
--- a/test/CacheDir/CACHEDIR_CLASS.py
+++ b/test/CacheDir/CACHEDIR_CLASS.py
@@ -30,9 +30,7 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
-test.dir_fixture('custom_cachedir')
-
-test.write(['CustomCacheDirModule.py'], """\
+test.write(['SConstruct'], """\
 import SCons
 class CustomCacheDir(SCons.CacheDir.CacheDir):
 
@@ -40,8 +38,15 @@ class CustomCacheDir(SCons.CacheDir.CacheDir):
     def copy_to_cache(cls, env, src, dst):
         print("MY_CUSTOM_CACHEDIR_CLASS")
         super().copy_to_cache(env, src, dst)
+
+env = Environment(tools=[])
+env['CACHEDIR_CLASS'] = CustomCacheDir
+env.CacheDir('cache')
+env.Command('file.out', 'file.in', Copy('$TARGET', '$SOURCE'))
 """)
 
+test.write('file.in', "file.in\n")
+
 test.run()
 
 test.must_contain_all_lines(test.stdout(), ["MY_CUSTOM_CACHEDIR_CLASS"])