Improve documentation of MSVC_VERSION and TARGET_ARCH.

1 files changed, 15 insertions, 8 deletions

diff --git a/src/engine/SCons/Tool/msvc.xml b/src/engine/SCons/Tool/msvc.xml
index e62a845..9e3e863 100644
--- a/src/engine/SCons/Tool/msvc.xml
+++ b/src/engine/SCons/Tool/msvc.xml
@@ -143,12 +143,12 @@ env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
 <cvar name="MSVC_BATCH">
 <summary>
 When set to any true value,
-specifies that &SCons; should batch
+specifies that SCons should batch
 compilation of object files
 when calling the Microsoft Visual C/C++ compiler.
 All compilations of source files from the same source directory
 that generate target files in a same output directory
-and were configured in &SCons; using the same construction environment
+and were configured in SCons using the same construction environment
 will be built in a single call to the compiler.
 Only source files that have changed since their
 object files were built will be passed to each compiler invocation
@@ -279,11 +279,12 @@ when the &cv-RCINCFLAGS; variable is expanded.
 <summary>
 Sets the preferred  version of Microsoft Visual C/C++ to use.
 
-If &cv-MSVC_VERSION; is not set,
-&SCons; will (by default) select the latest version
-of Visual C/C++ installed on your system.
-If the specified version isn't installed,
-tool initialization will fail.
+If &cv-MSVC_VERSION; is not set, SCons will (by default) select the
+latest version of Visual C/C++ installed on your system.  If the
+specified version isn't installed, tool initialization will fail.
+This variable must be passed as an argument to the Environment()
+constructor; setting it later has no effect.  Set it to an unexpected
+value (e.g. "XXX") to see the valid values on your system.
 </summary>
 </cvar>
 
@@ -292,6 +293,8 @@ tool initialization will fail.
 Sets the host architecture for Visual Studio compiler. If not set,
 default to the detected host architecture: note that this may depend
 on the python you are using.
+This variable must be passed as an argument to the Environment()
+constructor; setting it later has no effect. 
 
 Valid values are the same as for &cv-TARGET_ARCH;.
 
@@ -303,7 +306,11 @@ used on other OSes as well.
 <summary>
 Sets the target architecture for Visual Studio compiler (i.e. the arch
 of the binaries generated by the compiler). If not set, default to
-&cv-HOST_ARCH;.  
+&cv-HOST_ARCH;, or, if that is unset, to the architecture of the
+running machine's OS (note that the python build or architecture has no
+effect).
+This variable must be passed as an argument to the Environment()
+constructor; setting it later has no effect.  
 This is currently only used on Windows, but in the future it will be
 used on other OSes as well.