Docstring changes from Sphinx conversion [ci skip]

These changes are prompted by complaints Sphinx makes about
existing docstrings; split from the Sphinx-build PR to make
for easier reviewing.

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

11 files changed, 208 insertions, 159 deletions

diff --git a/SCons/Environment.py b/SCons/Environment.py
index cd52ee5..f9af099 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -1502,11 +1502,16 @@ class Base(SubstitutionEnvironment):
     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.
+        Args:
+          \*args (optional): variable names to look up
+
+        Returns:
+          If `args` omitted, the dictionary of all construction variables.
+          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 environment.
 
         """
         if not args:
@@ -1518,14 +1523,15 @@ class Base(SubstitutionEnvironment):
 
 
     def Dump(self, key=None, format='pretty'):
-        """ Serialize the construction variables to a string.
+        """ Return construction variables serialized to a string.
 
-        :param key: if None, format the whole dict of variables.
-            Else look up and format just the value for key.
-            
-        :param format: specify the format of the variables to be serialized:
-            - pretty: pretty-printed string.
-            - json: JSON-formatted string.
+        Args:
+          key (optional): if None, format the whole dict of variables.
+            Else format the value of `key` (Default value = None)
+          format (optional): specify the format to serialize to.
+            `"pretty"` generates a pretty-printed string,
+            `"json"` a JSON-formatted string.
+            (Default value = None, equivalent to `"pretty"`)
 
         """
         if key:
@@ -1556,12 +1562,15 @@ class Base(SubstitutionEnvironment):
 
 
     def FindIxes(self, paths, prefix, suffix):
-        """
-        Search a list of paths for something that matches the prefix and suffix.
+        """Search a list of paths for something that matches the prefix and suffix.
+
+        Args:
+          paths: the list of paths or nodes.
+          prefix: construction variable for the prefix.
+          suffix: construction variable for the suffix.
+
+        Returns: the matched path or None
 
-        paths - the list of paths or nodes.
-        prefix - construction variable for the prefix.
-        suffix - construction variable for the suffix.
         """
 
         suffix = self.subst('$'+suffix)
@@ -2017,7 +2026,7 @@ class Base(SubstitutionEnvironment):
             pass
         else:
             del kw['target_factory']
-            
+
         bld = SCons.Builder.Builder(**bkw)
         return bld(self, target, source, **kw)
 
diff --git a/SCons/Errors.py b/SCons/Errors.py
index a3a891f..ea94501 100644
--- a/SCons/Errors.py
+++ b/SCons/Errors.py
@@ -35,57 +35,53 @@ import SCons.Util
 
 
 class BuildError(Exception):
-    """ Errors occurring while building.
+    """SCons Errors that can occur while building.
 
-    BuildError have the following attributes:
-    =========================================
+    Attributes:
+      Information about the cause of the build error :
 
-    Information about the cause of the build error:
-    -----------------------------------------------
+      errstr: a description of the error message
 
-    errstr : a description of the error message
+      status: the return code of the action that caused the build error.
+        Must be set to a non-zero value even if the build error is not due
+        to an action returning a non-zero returned code.
 
-    status : the return code of the action that caused the build error.
-    Must be set to a non-zero value even if the build error is not due
-    to an action returning a non-zero returned code.
+      exitstatus: SCons exit status due to this build error.
+        Must be nonzero unless due to an explicit Exit()
+        call.  Not always the same as status, since
+        actions return a status code that should be
+        respected, but SCons typically exits with 2
+        irrespective of the return value of the failed
+        action.
 
-    exitstatus : SCons exit status due to this build error.
-    Must be nonzero unless due to an explicit Exit()
-    call.  Not always the same as status, since
-    actions return a status code that should be
-    respected, but SCons typically exits with 2
-    irrespective of the return value of the failed
-    action.
+      filename: The name of the file or directory that caused the
+        build error. Set to None if no files are associated with
+        this error. This might be different from the target
+        being built. For example, failure to create the
+        directory in which the target file will appear. It
+        can be None if the error is not due to a particular
+        filename.
 
-    filename : The name of the file or directory that caused the
-    build error. Set to None if no files are associated with
-    this error. This might be different from the target
-    being built. For example, failure to create the
-    directory in which the target file will appear. It
-    can be None if the error is not due to a particular
-    filename.
+      exc_info: Info about exception that caused the build
+        error. Set to (None, None, None) if this build
+        error is not due to an exception.
 
-    exc_info : Info about exception that caused the build
-    error. Set to (None, None, None) if this build
-    error is not due to an exception.
+      Information about the what caused the build error :
 
+      node: the error occured while building this target node(s)
 
-    Information about the cause of the location of the error:
-    ---------------------------------------------------------
+      executor: the executor that caused the build to fail (might
+        be None if the build failures is not due to the
+        executor failing)
 
-    node : the error occured while building this target node(s)
+      action: the action that caused the build to fail (might be
+        None if the build failures is not due to the an
+        action failure)
 
-    executor : the executor that caused the build to fail (might
-               be None if the build failures is not due to the
-               executor failing)
+      command: the command line for the action that caused the
+        build to fail (might be None if the build failures
+        is not due to the an action failure)
 
-    action : the action that caused the build to fail (might be
-             None if the build failures is not due to the an
-             action failure)
-
-    command : the command line for the action that caused the
-              build to fail (might be None if the build failures
-              is not due to the an action failure)
     """
 
     def __init__(self,
@@ -138,14 +134,15 @@ class ExplicitExit(Exception):
         Exception.__init__(self, *args)
 
 def convert_to_BuildError(status, exc_info=None):
-    """
-    Convert any return code a BuildError Exception.
-
-    :Parameters:
-      - `status`: can either be a return code or an Exception.
+    """Convert a return code to a BuildError Exception.
 
-    The buildError.status we set here will normally be
+    The `buildError.status` we set here will normally be
     used as the exit status of the "scons" process.
+
+    Args:
+      status: can either be a return code or an Exception.
+      exc_info (tuple, optional): explicit exception information.
+
     """
 
     if not exc_info and isinstance(status, Exception):
diff --git a/SCons/Platform/__init__.py b/SCons/Platform/__init__.py
index 12db824..e2a7b1e 100644
--- a/SCons/Platform/__init__.py
+++ b/SCons/Platform/__init__.py
@@ -56,10 +56,10 @@ import SCons.Tool
 
 
 def platform_default():
-    """Return the platform string for our execution environment.
+    r"""Return the platform string for our execution environment.
 
     The returned value should map to one of the SCons/Platform/*.py
-    files.  Since we're architecture independent, though, we don't
+    files.  Since scons is architecture independent, though, we don't
     care about the machine architecture.
     """
     osname = os.name
@@ -131,26 +131,33 @@ class PlatformSpec:
 
 
 class TempFileMunge:
-    """A callable class.  You can set an Environment variable to this,
-    then call it with a string argument, then it will perform temporary
-    file substitution on it.  This is used to circumvent the long command
-    line limitation.
+    """Convert long command lines to use a temporary file.
+
+    You can set an Environment variable (usually `TEMPFILE`) to this,
+    then call it with a string argument, and it will perform temporary
+    file substitution on it.  This is used to circumvent limitations on
+    the length of command lines. Example::
 
-    Example usage:
         env["TEMPFILE"] = TempFileMunge
         env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES','$LINKCOMSTR')}"
 
     By default, the name of the temporary file used begins with a
     prefix of '@'.  This may be configured for other tool chains by
-    setting '$TEMPFILEPREFIX':
+    setting the TEMPFILEPREFIX variable. Example::
+
         env["TEMPFILEPREFIX"] = '-@'        # diab compiler
         env["TEMPFILEPREFIX"] = '-via'      # arm tool chain
         env["TEMPFILEPREFIX"] = ''          # (the empty string) PC Lint
 
     You can configure the extension of the temporary file through the
     TEMPFILESUFFIX variable, which defaults to '.lnk' (see comments
-    in the code below):
+    in the code below). Example::
+
         env["TEMPFILESUFFIX"] = '.lnt'   # PC Lint
+
+    Entries in the temporary file are separated by the value of the
+    TEMPFILEARGJOIN variable, which defaults to an OS-appropriate value.
+
     """
     def __init__(self, cmd, cmdstr = None):
         self.cmd = cmd
diff --git a/SCons/Script/SConsOptions.py b/SCons/Script/SConsOptions.py
index 10600b6..9fee74e 100644
--- a/SCons/Script/SConsOptions.py
+++ b/SCons/Script/SConsOptions.py
@@ -332,29 +332,27 @@ class SConsOptionParser(optparse.OptionParser):
         option.process(opt, value, values, self)
 
     def reparse_local_options(self):
-        """
-        Re-parse the leftover command-line options stored
-        in self.largs, so that any value overridden on the
-        command line is immediately available if the user turns
-        around and does a GetOption() right away.
+        """ Re-parse the leftover command-line options.
 
-        We mimic the processing of the single args
-        in the original OptionParser._process_args(), but here we
-        allow exact matches for long-opts only (no partial
-        argument names!).
+        Parse options stored in `self.largs`, so that any value
+        overridden on the command line is immediately available
+        if the user turns around and does a :func:`GetOption` right away.
 
-        Else, this would lead to problems in add_local_option()
+        We mimic the processing of the single args
+        in the original OptionParser :func:`_process_args`, but here we
+        allow exact matches for long-opts only (no partial argument names!).
+        Otherwise there could be  problems in :func:`add_local_option`
         below. When called from there, we try to reparse the
         command-line arguments that
-          1. haven't been processed so far (self.largs), but
-          2. are possibly not added to the list of options yet.
-
-        So, when we only have a value for "--myargument" yet,
-        a command-line argument of "--myarg=test" would set it.
-        Responsible for this behaviour is the method
-        _match_long_opt(), which allows for partial matches of
-        the option name, as long as the common prefix appears to
-        be unique.
+
+        1. haven't been processed so far (`self.largs`), but
+        2. are possibly not added to the list of options yet.
+
+        So, when we only have a value for "--myargument" so far,
+        a command-line argument of "--myarg=test" would set it,
+        per the behaviour of :func:`_match_long_opt`,
+        which allows for partial matches of the option name,
+        as long as the common prefix appears to be unique.
         This would lead to further confusion, because we might want
         to add another option "--myarg" later on (see issue #2929).
 
diff --git a/SCons/Tool/dmd.py b/SCons/Tool/dmd.py
index 3cc4ed0..ba12131 100644
--- a/SCons/Tool/dmd.py
+++ b/SCons/Tool/dmd.py
@@ -10,22 +10,43 @@ Evolved by Russel Winder (russel@winder.org.uk)
 2010-02-07 onwards
 
 Compiler variables:
-    DC - The name of the D compiler to use.  Defaults to dmd or gdmd,
-        whichever is found.
-    DPATH - List of paths to search for import modules.
-    DVERSIONS - List of version tags to enable when compiling.
-    DDEBUG - List of debug tags to enable when compiling.
+
+DC
+  The name of the D compiler to use.
+  Defaults to dmd or gdmd, whichever is found.
+
+DPATH
+  List of paths to search for import modules.
+
+DVERSIONS
+  List of version tags to enable when compiling.
+
+DDEBUG
+  List of debug tags to enable when compiling.
 
 Linker related variables:
-    LIBS - List of library files to link in.
-    DLINK - Name of the linker to use.  Defaults to dmd or gdmd,
-        whichever is found.
-    DLINKFLAGS - List of linker flags.
+
+LIBS
+  List of library files to link in.
+
+DLINK
+  Name of the linker to use.
+  Defaults to dmd or gdmd, whichever is found.
+
+DLINKFLAGS
+  List of linker flags.
 
 Lib tool variables:
-    DLIB - Name of the lib tool to use.  Defaults to lib.
-    DLIBFLAGS - List of flags to pass to the lib tool.
-    LIBS - Same as for the linker. (libraries to pull into the .lib)
+
+DLIB
+  Name of the lib tool to use.  Defaults to lib.
+
+DLIBFLAGS
+  List of flags to pass to the lib tool.
+
+LIBS
+  Same as for the linker. (libraries to pull into the .lib)
+
 """
 
 #
diff --git a/SCons/Tool/intelc.py b/SCons/Tool/intelc.py
index 0880976..f555d22 100644
--- a/SCons/Tool/intelc.py
+++ b/SCons/Tool/intelc.py
@@ -387,13 +387,15 @@ def get_intel_compiler_top(version, abi):
 def generate(env, version=None, abi=None, topdir=None, verbose=0):
     r"""Add Builders and construction variables for Intel C/C++ compiler
     to an Environment.
-    args:
-      version: (string) compiler version to use, like "80"
-      abi:     (string) 'win32' or whatever Itanium version wants
-      topdir:  (string) compiler top dir, like
-                         "c:\Program Files\Intel\Compiler70"
-                        If topdir is used, version and abi are ignored.
-      verbose: (int)    if >0, prints compiler version used.
+
+    Args:
+      version (str): compiler version to use, like "80"
+      abi (str): 'win32' or whatever Itanium version wants
+      topdir (str): directory containing compiler tree, e.g.
+        "c:\\Program Files\\Intel\\Compiler70".
+        If `topdir` is used, `version` and `abi` are ignored.
+      verbose: if >0, prints compiler version used.
+
     """
     if not (is_mac or is_linux or is_windows):
         # can't handle this platform
diff --git a/SCons/Tool/packaging/rpm.py b/SCons/Tool/packaging/rpm.py
index 0e44bf9..a026e45 100644
--- a/SCons/Tool/packaging/rpm.py
+++ b/SCons/Tool/packaging/rpm.py
@@ -302,21 +302,24 @@ def build_specfile_filesection(spec, files):
     return str
 
 class SimpleTagCompiler:
-    """ This class is a simple string substition utility:
-    the replacement specfication is stored in the tagset dictionary, something
-    like:
-     { "abc"  : "cdef %s ",
-       "abc_" : "cdef %s %s" }
-
-    the compile function gets a value dictionary, which may look like:
-    { "abc"    : "ghij",
-      "abc_gh" : "ij" }
-
-    The resulting string will be:
-     "cdef ghij cdef gh ij"
+    """ Compile RPM tags by doing simple string substitution.
+
+    The replacement specfication is stored in the *tagset* dictionary,
+    something like::
+
+      {"abc" : "cdef %s ", "abc_": "cdef %s %s"}
+
+    The :func:`compile` function gets a value dictionary, which may look like::
+
+      {"abc": "ghij", "abc_gh": "ij"}
+
+    The resulting string will be::
+
+      "cdef ghij cdef gh ij"
+
     """
     def __init__(self, tagset, mandatory=1):
-        self.tagset    = tagset
+        self.tagset = tagset
         self.mandatory = mandatory
 
     def compile(self, values):
diff --git a/SCons/Util.py b/SCons/Util.py
index 1ec0cf8..ae204a1 100644
--- a/SCons/Util.py
+++ b/SCons/Util.py
@@ -1611,16 +1611,21 @@ def cmp(a, b):
 
 
 def get_env_bool(env, name, default=False):
-    """Get a value of env[name] converted to boolean. The value of env[name] is
-    interpreted as follows: 'true', 'yes', 'y', 'on' (case insensitive) and
-    anything convertible to int that yields non-zero integer are True values;
-    '0', 'false', 'no', 'n' and 'off' (case insensitive) are False values. For
-    all other cases, default value is returned.
-
-    :Parameters:
-        - `env`     - dict or dict-like object, a convainer with variables
-        - `name`    - name of the variable in env to be returned
-        - `default` - returned when env[name] does not exist or can't be converted to bool
+    """Convert a construction variable to bool.
+
+    If the value of *name* in *env* is 'true', 'yes', 'y', 'on' (case
+    insensitive) or anything convertible to int that yields non-zero then
+    return True; if 'false', 'no', 'n', 'off' (case insensitive)
+    or a number that converts to integer zero return False.
+    Otherwise, return *default*.
+
+    Args:
+        env: construction environment, or any dict-like object
+        name: name of the variable
+        default: value to return if *name* not in *env* or cannot
+          be converted (default: False)
+    Returns:
+        bool: the "truthiness" of *name*
     """
     try:
         var = env[name]
@@ -1638,7 +1643,10 @@ def get_env_bool(env, name, default=False):
 
 
 def get_os_env_bool(name, default=False):
-    """Same as get_env_bool(os.environ, name, default)."""
+    """Convert an environment variable to bool.
+
+    Conversion is the same as for :func:`get_env_bool`.
+    """
     return get_env_bool(os.environ, name, default)
 
 # Local Variables:
diff --git a/SCons/Variables/__init__.py b/SCons/Variables/__init__.py
index 59b63eb..ce9335b 100644
--- a/SCons/Variables/__init__.py
+++ b/SCons/Variables/__init__.py
@@ -48,17 +48,21 @@ class Variables:
     """
     Holds all the options, updates the environment with the variables,
     and renders the help text.
-    """
-    instance=None
 
-    def __init__(self, files=None, args=None, is_global=1):
-        """
-        files - [optional] List of option configuration files to load
-            (backward compatibility) If a single string is passed it is
-            automatically placed in a file list
-        args - dictionary to override values set from files.
-        """
+    If is_global is True, this is a singleton, create only once.
 
+    Args:
+      files (optional): List of option configuration files to load
+        (backward compatibility). If a single string is passed it is
+        automatically placed in a file list (Default value = None)
+      args (optional): dictionary to override values set from *files*.
+        (Default value = None)
+      is_global (optional): global instance? (Default value = True)
+
+    """
+    instance = None
+
+    def __init__(self, files=None, args=None, is_global=True):
         if args is None:
             args = {}
         self.options = []
@@ -112,18 +116,19 @@ class Variables:
         return [o.key for o in self.options]
 
     def Add(self, key, help="", default=None, validator=None, converter=None, **kw):
-        """
-        Add an option.
+        """Add an option.
+
+        Args:
+          key: the name of the variable, or a list or tuple of arguments
+          help: optional help text for the options (Default value = "")
+          default: optional default value for option (Default value = None)
+          validator: optional function called to validate the option's value
+            (Default value = None)
+          converter: optional function to be called to convert the option's
+            value before putting it in the environment. (Default value = None)
+          \*\*kw: keyword args, unused.
 
-
-        @param key: the name of the variable, or a list or tuple of arguments
-        @param help: optional help text for the options
-        @param default: optional default value
-        @param validator: optional function that is called to validate the option's value
-        @type validator: Called with (key, value, environment)
-        @param converter: optional function that is called to convert the option's value before putting it in the environment.
         """
-
         if SCons.Util.is_List(key) or isinstance(key, tuple):
             self._do_add(*key)
             return
@@ -144,10 +149,9 @@ class Variables:
         Example::
 
             opt.AddVariables(
-            ('debug', '', 0),
-            ('CC', 'The C compiler'),
-            ('VALIDATE', 'An option for testing validation', 'notset',
-             validator, None),
+                ('debug', '', 0),
+                ('CC', 'The C compiler'),
+                ('VALIDATE', 'An option for testing validation', 'notset', validator, None),
             )
 
         """
diff --git a/SCons/cpp.py b/SCons/cpp.py
index 1113be5..0811c71 100644
--- a/SCons/cpp.py
+++ b/SCons/cpp.py
@@ -603,8 +603,7 @@ class PreProcessor:
 
         This handles recursive expansion of values without "" or <>
         surrounding the name until an initial " or < is found, to handle
-                #include FILE
-        where FILE is a #define somewhere else.
+        #include FILE where FILE is a #define somewhere else.
         """
         s = t[1].strip()
         while not s[0] in '<"':
diff --git a/SCons/dblite.py b/SCons/dblite.py
index b9269f1..338dcc7 100644
--- a/SCons/dblite.py
+++ b/SCons/dblite.py
@@ -37,6 +37,7 @@ class dblite:
 
     See the discussion at:
       http://mail.python.org/pipermail/python-bugs-list/2003-March/016877.html
+
     """
 
     _open = open