[PR 3462] update doc/comments for msvc-env-cache

Signed-off-by: Mats Wichmann <mats@linux.com>

2 files changed, 15 insertions, 8 deletions

diff --git a/src/engine/SCons/Tool/MSCommon/common.py b/src/engine/SCons/Tool/MSCommon/common.py
index ad371e9..bbccf61 100644
--- a/src/engine/SCons/Tool/MSCommon/common.py
+++ b/src/engine/SCons/Tool/MSCommon/common.py
@@ -36,7 +36,7 @@ import sys
 
 import SCons.Util
 
-# internal-use so undocumented:
+# SCONS_MSCOMMON_DEBUG is internal-use so undocumented:
 # set to '-' to print to console, else set to filename to log to
 LOGFILE = os.environ.get('SCONS_MSCOMMON_DEBUG')
 if LOGFILE == '-':
@@ -53,6 +53,7 @@ else:
     debug = lambda x: None
 
 
+# SCONS_CACHE_MSVC_CONFIG is public, and is documented.
 CONFIG_CACHE = os.environ.get('SCONS_CACHE_MSVC_CONFIG')
 if CONFIG_CACHE in ('1', 'true', 'True'):
     CONFIG_CACHE = os.path.join(os.path.expanduser('~'), '.scons_msvc_cache')
@@ -66,6 +67,7 @@ def read_script_env_cache():
                 envcache = json.load(f)
         #TODO can use more specific FileNotFoundError when py2 dropped
         except IOError:
+            # don't fail if no cache file, just proceed without it
             pass
     return envcache
 
diff --git a/src/engine/SCons/Tool/MSCommon/vc.py b/src/engine/SCons/Tool/MSCommon/vc.py
index d321f43..4f6048d 100644
--- a/src/engine/SCons/Tool/MSCommon/vc.py
+++ b/src/engine/SCons/Tool/MSCommon/vc.py
@@ -591,12 +591,15 @@ def reset_installed_vcs():
 # we can greatly improve the speed of the second and subsequent Environment
 # (or Clone) calls by memoizing the environment variables set by vcvars*.bat.
 #
-# Updated: by 2018, vcvarsall.bat had gotten so expensive it was breaking
-# CI builds because the test suite starts scons so many times and the existing
-# memo logic only helped with repeated calls within the same scons run;
-# with VS2019 it got even slower and an optional cache file was introduced.
-# The cache now also stores only the parsed vars, not the entire output
-# of running the batch file - saves a bit of time not parsing every time.
+# Updated: by 2018, vcvarsall.bat had gotten so expensive (vs2017 era)
+# it was breaking CI builds because the test suite starts scons so many
+# times and the existing memo logic only helped with repeated calls
+# within the same scons run. Windows builds on the CI system were split
+# into chunks to get around single-build time limits.
+# With VS2019 it got even slower and an optional persistent cache file
+# was introduced. The cache now also stores only the parsed vars, 
+# not the entire output of running the batch file - saves a bit
+# of time not parsing every time.
 
 script_env_cache = None
 
@@ -621,7 +624,8 @@ def script_env(script, args=None):
         # once we updated cache, give a chance to write out if user wanted
         common.write_script_env_cache(script_env_cache)
     else:
-        # if we "hit" data from the json file, we have a Py2 problem:
+        #TODO: Python 2 cleanup
+        # If we "hit" data from the json file, we have a Py2 problem:
         # keys & values will be unicode. don't detect, just convert.
         if sys.version_info[0] == 2:
             def convert(data):
@@ -635,6 +639,7 @@ def script_env(script, args=None):
                     return data
 
             cache_data = convert(cache_data)
+ 
     return cache_data
 
 def get_default_version(env):