Move verify invocation to last line of vc.py. Add verify method to Config module to check that

all _VCVER versions are defined locally.  Update module docstrings for Dispatcher and MSVC init.

4 files changed, 52 insertions, 5 deletions

diff --git a/SCons/Tool/MSCommon/MSVC/Config.py b/SCons/Tool/MSCommon/MSVC/Config.py
index 8f3a2cc..a4cb874 100644
--- a/SCons/Tool/MSCommon/MSVC/Config.py
+++ b/SCons/Tool/MSCommon/MSVC/Config.py
@@ -29,6 +29,12 @@ from collections import (
     namedtuple,
 )
 
+from . import Util
+
+from .Exceptions import (
+    MSVCInternalError,
+)
+
 from . import Dispatcher
 Dispatcher.register_modulename(__name__)
 
@@ -282,3 +288,12 @@ for policy_value, policy_symbol_list in [
         MSVC_NOTFOUND_POLICY_EXTERNAL[policy_symbol] = policy_def
         MSVC_NOTFOUND_POLICY_EXTERNAL[policy_symbol.upper()] = policy_def
 
+def verify():
+    from .. import vc
+    for msvc_version in vc._VCVER:
+        vc_version = Util.get_version_prefix(msvc_version)
+        if vc_version in MSVC_VERSION_INTERNAL:
+            continue
+        err_msg = 'vc_version {} not in MSVC_VERSION_INTERNAL'.format(repr(vc_version))
+        raise MSVCInternalError(err_msg)
+
diff --git a/SCons/Tool/MSCommon/MSVC/Dispatcher.py b/SCons/Tool/MSCommon/MSVC/Dispatcher.py
index 0b216ca..dab1e15 100644
--- a/SCons/Tool/MSCommon/MSVC/Dispatcher.py
+++ b/SCons/Tool/MSCommon/MSVC/Dispatcher.py
@@ -23,6 +23,25 @@
 
 """
 Internal method dispatcher for Microsoft Visual C/C++.
+
+MSVC modules can register their module (register_modulename) and individual
+classes (register_class) with the method dispatcher during initialization. MSVC
+modules tend to be registered immediately after the Dispatcher import near the
+top of the file. Methods in the MSVC modules can be invoked indirectly without
+having to hard-code the method calls effectively decoupling the upstream module
+with the downstream modules:
+
+The reset method dispatches calls to all registered objects with a reset method
+and/or a _reset method. The reset methods are used to restore data structures
+to their initial state for testing purposes. Typically, this involves clearing
+cached values.
+
+The verify method dispatches calls to all registered objects with a verify
+method and/or a _verify method. The verify methods are used to check that
+initialized data structures distributed across multiple modules are internally
+consistent.  An exception is raised when a verification constraint violation
+is detected.  Typically, this verifies that initialized dictionaries support
+all of the requisite keys as new versions are added.
 """
 
 import sys
@@ -34,13 +53,13 @@ from ..common import (
 
 _refs = []
 
-def register_class(ref):
-    _refs.append(ref)
-
 def register_modulename(modname):
     module = sys.modules[modname]
     _refs.append(module)
 
+def register_class(ref):
+    _refs.append(ref)
+
 def reset():
     debug('')
     for ref in _refs:
diff --git a/SCons/Tool/MSCommon/MSVC/__init__.py b/SCons/Tool/MSCommon/MSVC/__init__.py
index c07e849..b0ef5dd 100644
--- a/SCons/Tool/MSCommon/MSVC/__init__.py
+++ b/SCons/Tool/MSCommon/MSVC/__init__.py
@@ -23,6 +23,16 @@
 
 """
 Functions for Microsoft Visual C/C++.
+
+The reset method is used to restore MSVC module data structures to their
+initial state for testing purposes.
+
+The verify method is used as a sanity check that MSVC module data structures
+are internally consistent.
+
+Currently:
+* reset is invoked from reset_installed_vcs in the vc module.
+* verify is invoked from the last line in the vc module.
 """
 
 from . import Exceptions  # noqa: F401
@@ -40,6 +50,6 @@ from . import Dispatcher as _Dispatcher
 def reset():
     _Dispatcher.reset()
 
-#reset() # testing
-_Dispatcher.verify()
+def verify():
+    _Dispatcher.verify()
 
diff --git a/SCons/Tool/MSCommon/vc.py b/SCons/Tool/MSCommon/vc.py
index 675b8d0..7c65879 100644
--- a/SCons/Tool/MSCommon/vc.py
+++ b/SCons/Tool/MSCommon/vc.py
@@ -1352,3 +1352,6 @@ def get_msvc_sdk_versions(msvc_version=None, msvc_uwp_app=False):
     rval = MSVC.WinSDK.get_msvc_sdk_version_list(msvc_version, msvc_uwp_app)
     return rval
 
+# internal consistency check (should be last)
+MSVC.verify()
+