Update Dictionary documentation to match implementation [ci skip]

Dictionary is now described as returning a dict only if called
with no arguments; if called with arguments it returns a string
or list of strings (matching the implmenentation).

Note env.Dump() only takes zero arguments or one, it it not
documented as taking the multiple keys, so there's less ambiguity
with it.

Some examples twiddled a little, and in a couple of cases
Dictionary is not used any longer - we might as well just index
into the construction environment since that works.

Fixes #3156

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

2 files changed, 39 insertions, 18 deletions

diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py
index 5faa2d0..2e1e742 100644
--- a/src/engine/SCons/Environment.py
+++ b/src/engine/SCons/Environment.py
@@ -1493,8 +1493,14 @@ class Base(SubstitutionEnvironment):
 
         self.copy_from_cache = copy_function
 
+
     def Detect(self, progs):
         """Return the first available program in progs.
+
+        :param progs: one or more command names to check for
+        :type progs: str or list
+        :returns str: first name from progs that can be found.
+
         """
         if not SCons.Util.is_List(progs):
             progs = [ progs ]
@@ -1503,7 +1509,17 @@ class Base(SubstitutionEnvironment):
             if path: return prog
         return None
 
+
     def Dictionary(self, *args):
+        """Return construction variables from an environment.
+
+        :param *args: (optional) variable names to look up
+        :returns: if args omitted, the dictionary of all constr. vars.
+            If one arg, the corresponding value is returned.
+            If more than one arg, a list of values is returned.
+        :raises KeyError: if any of *args is not in the construction env.
+
+        """
         if not args:
             return self._dict
         dlist = [self._dict[x] for x in args]
@@ -1511,23 +1527,28 @@ class Base(SubstitutionEnvironment):
             dlist = dlist[0]
         return dlist
 
-    def Dump(self, key = None):
-        """
-        Using the standard Python pretty printer, return the contents of the
-        scons build environment as a string.
 
-        If the key passed in is anything other than None, then that will
-        be used as an index into the build environment dictionary and
-        whatever is found there will be fed into the pretty printer. Note
-        that this key is case sensitive.
+    def Dump(self, key=None):
+        """ Return pretty-printed string of construction variables.
+
+        :param key: if None, format the whole dict of variables.
+            Else look up and format just the value for key.
+
         """
         import pprint
         pp = pprint.PrettyPrinter(indent=2)
         if key:
-            dict = self.Dictionary(key)
+            cvars = self.Dictionary(key)
         else:
-            dict = self.Dictionary()
-        return pp.pformat(dict)
+            cvars = self.Dictionary()
+
+        # TODO: pprint doesn't do a nice job on path-style values
+        # if the paths contain spaces (i.e. Windows), because the
+        # algorithm tries to break lines on spaces, while breaking
+        # on the path-separator would be more "natural". Is there
+        # a better way to format those?
+        return pp.pformat(cvars)
+
 
     def FindIxes(self, paths, prefix, suffix):
         """
diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml
index 46a00d2..3f12b4f 100644
--- a/src/engine/SCons/Environment.xml
+++ b/src/engine/SCons/Environment.xml
@@ -1325,11 +1325,11 @@ env.Depends(bar, installed_lib)
 <summary>
 <para>
 Returns a dictionary object
-containing copies of all of the
-construction variables in the environment.
-If there are any variable names specified,
-only the specified construction
-variables are returned in the dictionary.
+containing construction variables in the environment.
+If there are any arguments specified,
+only the values of the specified construction
+variables are returned as a string (if one
+argument) or as a list of strings.
 </para>
 
 <para>
@@ -1337,8 +1337,8 @@ Example:
 </para>
 
 <example_commands>
-dict = env.Dictionary()
-cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
+cvars = env.Dictionary()
+cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
 </example_commands>
 </summary>
 </scons_function>