Fix many epydoc warnings

22 files changed, 251 insertions, 239 deletions

diff --git a/src/engine/SCons/Action.py b/src/engine/SCons/Action.py
index d6fe30b4..b44088bf 100644
--- a/src/engine/SCons/Action.py
+++ b/src/engine/SCons/Action.py
@@ -222,9 +222,10 @@ def _code_contents(code, docstring=None):
     recompilations from moving a Python function.
 
     See:
-      * https://docs.python.org/2/library/inspect.html
-      * http://python-reference.readthedocs.io/en/latest/docs/code/index.html
-    For info on what each co_ variable provides
+      - https://docs.python.org/2/library/inspect.html
+      - http://python-reference.readthedocs.io/en/latest/docs/code/index.html
+
+    For info on what each co\_ variable provides
 
     The signature is as follows (should be byte/chars):
     co_argcount, len(co_varnames), len(co_cellvars), len(co_freevars),
@@ -281,8 +282,7 @@ def _code_contents(code, docstring=None):
 
 
 def _function_contents(func):
-    """Return the signature contents of a function.
-
+    """
     The signature is as follows (should be byte/chars):
     < _code_contents (see above) from func.__code__ >
     ,( comma separated _object_contents for function argument defaults)
@@ -290,10 +290,12 @@ def _function_contents(func):
 
 
     See also: https://docs.python.org/3/reference/datamodel.html
-    func.__code__     - The code object representing the compiled function body.
-    func.__defaults__ - A tuple containing default argument values for those arguments
-                        that have defaults, or None if no arguments have a default value
-    func.__closure__  - None or a tuple of cells that contain bindings for the function's free variables.
+      - func.__code__     - The code object representing the compiled function body.
+      - func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value
+      - func.__closure__  - None or a tuple of cells that contain bindings for the function's free variables.
+
+    :Returns:
+      Signature contents of a function. (in bytes)
     """
 
     contents = [_code_contents(func.__code__, func.__doc__)]
@@ -330,9 +332,12 @@ def _function_contents(func):
 def _object_instance_content(obj):
     """
     Returns consistant content for a action class or an instance thereof
-    :param obj: Should be either and action class or an instance thereof
-    :return: bytearray or bytes representing the obj suitable for generating
-             a signiture from.
+
+    :Parameters:
+      - `obj` Should be either and action class or an instance thereof
+
+    :Returns:
+      bytearray or bytes representing the obj suitable for generating a signature from.
     """
     retval = bytearray()
 
diff --git a/src/engine/SCons/Builder.py b/src/engine/SCons/Builder.py
index 21f1b4ae..afc2cf0d 100644
--- a/src/engine/SCons/Builder.py
+++ b/src/engine/SCons/Builder.py
@@ -1,4 +1,5 @@
-"""SCons.Builder
+"""
+SCons.Builder
 
 Builder object subsystem.
 
@@ -31,7 +32,7 @@ There is also a proxy that looks like a Builder:
 Builders and their proxies have the following public interface methods
 used by other modules:
 
-    __call__()
+    - __call__()
         THE public interface.  Calling a Builder object (with the
         use of internal helper methods) sets up the target and source
         dependencies, appropriate mapping to a specific action, and the
@@ -39,12 +40,12 @@ used by other modules:
         variable.  This also takes care of warning about possible mistakes
         in keyword arguments.
 
-    add_emitter()
+    - add_emitter()
         Adds an emitter for a specific file suffix, used by some Tool
         modules to specify that (for example) a yacc invocation on a .y
         can create a .h *and* a .c file.
 
-    add_action()
+    - add_action()
         Adds an action for a specific file suffix, heavily used by
         Tool modules to add their specific action(s) for turning
         a source file into an object file to the global static
@@ -52,23 +53,23 @@ used by other modules:
 
 There are the following methods for internal use within this module:
 
-    _execute()
+    - _execute()
         The internal method that handles the heavily lifting when a
         Builder is called.  This is used so that the __call__() methods
         can set up warning about possible mistakes in keyword-argument
         overrides, and *then* execute all of the steps necessary so that
         the warnings only occur once.
 
-    get_name()
+    - get_name()
         Returns the Builder's name within a specific Environment,
         primarily used to try to return helpful information in error
         messages.
 
-    adjust_suffix()
-    get_prefix()
-    get_suffix()
-    get_src_suffix()
-    set_src_suffix()
+    - adjust_suffix()
+    - get_prefix()
+    - get_suffix()
+    - get_src_suffix()
+    - set_src_suffix()
         Miscellaneous stuff for handling the prefix and suffix
         manipulation we use in turning source file names into target
         file names.
diff --git a/src/engine/SCons/Conftest.py b/src/engine/SCons/Conftest.py
index 4db7e062..abaf00d4 100644
--- a/src/engine/SCons/Conftest.py
+++ b/src/engine/SCons/Conftest.py
@@ -706,11 +706,12 @@ def CheckProg(context, prog_name):
 def _YesNoResult(context, ret, key, text, comment = None):
     """
     Handle the result of a test with a "yes" or "no" result.
-    "ret" is the return value: empty if OK, error message when not.
-    "key" is the name of the symbol to be defined (HAVE_foo).
-    "text" is the source code of the program used for testing.
-    "comment" is the C comment to add above the line defining the symbol (the
-    comment is automatically put inside a /* */). If None, no comment is added.
+
+    :Parameters:
+      - `ret` is the return value: empty if OK, error message when not.
+      - `key` is the name of the symbol to be defined (HAVE_foo).
+      - `text` is the source code of the program used for testing.
+      - `comment` is the C comment to add above the line defining the symbol (the comment is automatically put inside a /\* \*/). If None, no comment is added.
     """
     if key:
         _Have(context, key, not ret, comment)
@@ -724,18 +725,20 @@ def _YesNoResult(context, ret, key, text, comment = None):
 def _Have(context, key, have, comment = None):
     """
     Store result of a test in context.havedict and context.headerfilename.
-    "key" is a "HAVE_abc" name.  It is turned into all CAPITALS and non-
-    alphanumerics are replaced by an underscore.
+
+    :Parameters:
+      - `key` - is a "HAVE_abc" name.  It is turned into all CAPITALS and non-alphanumerics are replaced by an underscore.
+      - `have`   - value as it should appear in the header file, include quotes when desired and escape special characters!
+      - `comment` is the C comment to add above the line defining the symbol (the comment is automatically put inside a /\* \*/). If None, no comment is added.
+
+
     The value of "have" can be:
-    1      - Feature is defined, add "#define key".
-    0      - Feature is not defined, add "/* #undef key */".
-             Adding "undef" is what autoconf does.  Not useful for the
-             compiler, but it shows that the test was done.
-    number - Feature is defined to this number "#define key have".
-             Doesn't work for 0 or 1, use a string then.
-    string - Feature is defined to this string "#define key have".
-             Give "have" as is should appear in the header file, include quotes
-             when desired and escape special characters!
+      - 1      - Feature is defined, add "#define key".
+      - 0      - Feature is not defined, add "/\* #undef key \*/". Adding "undef" is what autoconf does.  Not useful for the compiler, but it shows that the test was done.
+      - number - Feature is defined to this number "#define key have". Doesn't work for 0 or 1, use a string then.
+      - string - Feature is defined to this string "#define key have".
+
+
     """
     key_up = key.upper()
     key_up = re.sub('[^A-Z0-9_]', '_', key_up)
@@ -786,10 +789,11 @@ def _lang2suffix(lang):
     When "lang" is empty or None C is assumed.
     Returns a tuple (lang, suffix, None) when it works.
     For an unrecognized language returns (None, None, msg).
+
     Where:
-        lang   = the unified language name
-        suffix = the suffix, including the leading dot
-        msg    = an error message
+      - lang   = the unified language name
+      - suffix = the suffix, including the leading dot
+      - msg    = an error message
     """
     if not lang or lang in ["C", "c"]:
         return ("C", ".c", None)
diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py
index 6a127db5..42b28e61 100644
--- a/src/engine/SCons/Environment.py
+++ b/src/engine/SCons/Environment.py
@@ -2189,13 +2189,16 @@ class Base(SubstitutionEnvironment):
         """This function converts a string or list into a list of strings
         or Nodes.  This makes things easier for users by allowing files to
         be specified as a white-space separated list to be split.
+
         The input rules are:
             - A single string containing names separated by spaces. These will be
               split apart at the spaces.
             - A single Node instance
             - A list containing either strings or Node instances. Any strings
               in the list are not split at spaces.
+
         In all cases, the function returns a list of Nodes and strings."""
+
         if SCons.Util.is_List(arg):
             return list(map(self.subst, arg))
         elif SCons.Util.is_String(arg):
diff --git a/src/engine/SCons/Errors.py b/src/engine/SCons/Errors.py
index 1df8cb91..2ba007cc 100644
--- a/src/engine/SCons/Errors.py
+++ b/src/engine/SCons/Errors.py
@@ -38,55 +38,55 @@ class BuildError(Exception):
     """ Errors occurring while building.
 
     BuildError have the following 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 cause of the location of the error:
-        ---------------------------------------------------------
+    Information about the cause of the location of the error:
+    ---------------------------------------------------------
 
-        node : the error occured while building this target node(s)
-        
-        executor : the executor that caused the build to fail (might
-                   be None if the build failures is not due to the
-                   executor failing)
-        
-        action : the action that caused the build to fail (might be
-                 None if the build failures is not due to the an
-                 action failure)
+    node : the error occured while building this target node(s)
 
-        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)
-        """
+    executor : the executor that caused the build to fail (might
+               be None if the build failures is not due to the
+               executor failing)
+
+    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,
                  node=None, errstr="Unknown error", status=2, exitstatus=2,
@@ -94,7 +94,6 @@ class BuildError(Exception):
                  exc_info=(None, None, None)):
 
         # py3: errstr should be string and not bytes.
-        # import pdb; pdb.set_trace()
 
         self.errstr = SCons.Util.to_str(errstr)
         self.status = status
@@ -142,13 +141,13 @@ def convert_to_BuildError(status, exc_info=None):
     """
     Convert any return code a BuildError Exception.
 
-    `status' can either be a return code or an Exception.
+    :Parameters:
+      - `status`: can either be a return code or an Exception.
+
     The buildError.status we set here will normally be
     used as the exit status of the "scons" process.
     """
 
-    # import pdb; pdb.set_trace()
-
     if not exc_info and isinstance(status, Exception):
         exc_info = (status.__class__, status, None)
 
diff --git a/src/engine/SCons/Memoize.py b/src/engine/SCons/Memoize.py
index 9774bdd3..5bdcf42b 100644
--- a/src/engine/SCons/Memoize.py
+++ b/src/engine/SCons/Memoize.py
@@ -34,7 +34,7 @@ values in a consistent way. In particular, it requires that the class uses a
 dictionary named "_memo" to store the cached values.
 
 Here is an example of wrapping a method that returns a computed value,
-with no input parameters:
+with no input parameters::
 
     @SCons.Memoize.CountMethodCall
     def foo(self):
@@ -51,7 +51,7 @@ with no input parameters:
         return result
 
 Here is an example of wrapping a method that will return different values
-based on one or more input arguments:
+based on one or more input arguments::
 
     def _bar_key(self, argument):                               # Memoization
         return argument                                         # Memoization
diff --git a/src/engine/SCons/Node/FS.py b/src/engine/SCons/Node/FS.py
index c31ac6c4..684f0d11 100644
--- a/src/engine/SCons/Node/FS.py
+++ b/src/engine/SCons/Node/FS.py
@@ -559,14 +559,13 @@ class Base(SCons.Node.Node):
         our relative and absolute paths, identify our parent
         directory, and indicate that this node should use
         signatures."""
+
         if SCons.Debug.track_instances: logInstanceCreation(self, 'Node.FS.Base')
         SCons.Node.Node.__init__(self)
 
-        # Filenames and paths are probably reused and are intern'ed to
-        # save some memory.
-
-        #: Filename with extension as it was specified when the object was
-        #: created; to obtain filesystem path, use Python str() function
+        # Filenames and paths are probably reused and are intern'ed to save some memory.
+        # Filename with extension as it was specified when the object was
+        # created; to obtain filesystem path, use Python str() function
         self.name = SCons.Util.silent_intern(name)
         self.fs = fs #: Reference to parent Node.FS object
 
@@ -2255,8 +2254,8 @@ class RootDir(Dir):
             name = drive
             dirname = drive + OS_SEP
 
-        #: Filename with extension as it was specified when the object was
-        #: created; to obtain filesystem path, use Python str() function
+        # Filename with extension as it was specified when the object was
+        # created; to obtain filesystem path, use Python str() function
         self.name = SCons.Util.silent_intern(name)
         self.fs = fs #: Reference to parent Node.FS object
 
@@ -2959,7 +2958,7 @@ class File(Base):
          We'd like to remove a lot more attributes like self.sources
          and self.sources_set, but they might get used
          in a next build step. For example, during configuration
-         the source files for a built *.o file are used to figure out
+         the source files for a built E{*}.o file are used to figure out
          which linker to use for the resulting Program (gcc vs. g++)!
          That's why we check for the 'keep_targetinfo' attribute,
          config Nodes and the Interactive mode just don't allow
@@ -3448,20 +3447,15 @@ class FileFinder(object):
     @SCons.Memoize.CountDictCall(_find_file_key)
     def find_file(self, filename, paths, verbose=None):
         """
-        find_file(str, [Dir()]) -> [nodes]
+        Find a node corresponding to either a derived file or a file that exists already.
 
-        filename - a filename to find
-        paths - a list of directory path *nodes* to search in.  Can be
-                represented as a list, a tuple, or a callable that is
-                called with no arguments and returns the list or tuple.
+        Only the first file found is returned, and none is returned if no file is found.
 
-        returns - the node created from the found file.
+        filename: A filename to find
+        paths: A list of directory path *nodes* to search in.  Can be represented as a list, a tuple, or a callable that is called with no arguments and returns the list or tuple.
 
-        Find a node corresponding to either a derived file or a file
-        that exists already.
+        returns The node created from the found file.
 
-        Only the first file found is returned, and none is returned
-        if no file is found.
         """
         memo_key = self._find_file_key(filename, paths)
         try:
diff --git a/src/engine/SCons/SConf.py b/src/engine/SCons/SConf.py
index 889af4a0..48eed8ee 100644
--- a/src/engine/SCons/SConf.py
+++ b/src/engine/SCons/SConf.py
@@ -459,9 +459,9 @@ class SConfBase(object):
         If value is None (default), then #define name is written. If value is not
         none, then #define name value is written.
 
-        comment is a string which will be put as a C comment in the
-        header, to explain the meaning of the value (appropriate C comments /* and
-        */ will be put automatically."""
+        comment is a string which will be put as a C comment in the header, to explain the meaning of the value
+        (appropriate C comments will be added automatically).
+        """
         lines = []
         if comment:
             comment_str = "/* %s */" % comment
diff --git a/src/engine/SCons/Scanner/LaTeX.py b/src/engine/SCons/Scanner/LaTeX.py
index e5abb0c2..5800443a 100644
--- a/src/engine/SCons/Scanner/LaTeX.py
+++ b/src/engine/SCons/Scanner/LaTeX.py
@@ -78,8 +78,10 @@ def modify_env_var(env, var, abspath):
     return save
 
 class FindENVPathDirs(object):
-    """A class to bind a specific *PATH variable name to a function that
-    will return all of the *path directories."""
+    """
+    A class to bind a specific E{*}PATH variable name to a function that
+    will return all of the E{*}path directories.
+    """
     def __init__(self, variable):
         self.variable = variable
     def __call__(self, env, dir=None, target=None, source=None, argument=None):
@@ -96,7 +98,8 @@ class FindENVPathDirs(object):
 
 
 def LaTeXScanner():
-    """Return a prototype Scanner instance for scanning LaTeX source files
+    """
+    Return a prototype Scanner instance for scanning LaTeX source files
     when built with latex.
     """
     ds = LaTeX(name = "LaTeXScanner",
@@ -107,7 +110,8 @@ def LaTeXScanner():
     return ds
 
 def PDFLaTeXScanner():
-    """Return a prototype Scanner instance for scanning LaTeX source files
+    """
+    Return a prototype Scanner instance for scanning LaTeX source files
     when built with pdflatex.
     """
     ds = LaTeX(name = "PDFLaTeXScanner",
@@ -118,7 +122,8 @@ def PDFLaTeXScanner():
     return ds
 
 class LaTeX(SCons.Scanner.Base):
-    """Class for scanning LaTeX files for included files.
+    """
+    Class for scanning LaTeX files for included files.
 
     Unlike most scanners, which use regular expressions that just
     return the included file name, this returns a tuple consisting
@@ -135,10 +140,12 @@ class LaTeX(SCons.Scanner.Base):
     
     The actual subset and search order may be altered by
     DeclareGraphicsExtensions command. This complication is ignored.
-    The default order corresponds to experimentation with teTeX
+    The default order corresponds to experimentation with teTeX::
+
         $ latex --version
         pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4)
         kpathsea version 3.5.4
+
     The order is:
         ['.eps', '.ps'] for latex
         ['.png', '.pdf', '.jpg', '.tif'].
@@ -150,8 +157,7 @@ class LaTeX(SCons.Scanner.Base):
     env['TEXINPUTS'] for "lstinputlisting" keyword
     env['BIBINPUTS'] for "bibliography" keyword
     env['BSTINPUTS'] for "bibliographystyle" keyword
-    env['INDEXSTYLE'] for "makeindex" keyword, no scanning support needed
-                      just allows user to set it if needed.
+    env['INDEXSTYLE'] for "makeindex" keyword, no scanning support needed just allows user to set it if needed.
 
     FIXME: also look for the class or style in document[class|style]{}
     FIXME: also look for the argument of bibliographystyle{}
diff --git a/src/engine/SCons/Scanner/__init__.py b/src/engine/SCons/Scanner/__init__.py
index c0f1a933..f7828abe 100644
--- a/src/engine/SCons/Scanner/__init__.py
+++ b/src/engine/SCons/Scanner/__init__.py
@@ -62,8 +62,10 @@ def Scanner(function, *args, **kw):
 
 
 class FindPathDirs(object):
-    """A class to bind a specific *PATH variable name to a function that
-    will return all of the *path directories."""
+    """
+    A class to bind a specific E{*}PATH variable name to a function that
+    will return all of the E{*}path directories.
+    """
     def __init__(self, variable):
         self.variable = variable
     def __call__(self, env, dir=None, target=None, source=None, argument=None):
diff --git a/src/engine/SCons/Script/Interactive.py b/src/engine/SCons/Script/Interactive.py
index 6be7b270..cc4f23cf 100644
--- a/src/engine/SCons/Script/Interactive.py
+++ b/src/engine/SCons/Script/Interactive.py
@@ -99,17 +99,14 @@ except ImportError:
 
 class SConsInteractiveCmd(cmd.Cmd):
     """\
-    build [TARGETS]         Build the specified TARGETS and their dependencies.
-                            'b' is a synonym.
-    clean [TARGETS]         Clean (remove) the specified TARGETS and their
-                            dependencies.  'c' is a synonym.
-    exit                    Exit SCons interactive mode.
-    help [COMMAND]          Prints help for the specified COMMAND.  'h' and
-                            '?' are synonyms.
-    shell [COMMANDLINE]     Execute COMMANDLINE in a subshell.  'sh' and '!'
-                            are synonyms.
-    version                 Prints SCons version information.
-    """
+
+build [TARGETS]         Build the specified TARGETS and their dependencies. 'b' is a synonym.
+clean [TARGETS]         Clean (remove) the specified TARGETS and their dependencies.  'c' is a synonym.
+exit                    Exit SCons interactive mode.
+help [COMMAND]          Prints help for the specified COMMAND.  'h' and '?' are synonyms.
+shell [COMMANDLINE]     Execute COMMANDLINE in a subshell.  'sh' and '!' are synonyms.
+version                 Prints SCons version information.
+"""
 
     synonyms = {
         'b'     : 'build',
diff --git a/src/engine/SCons/Taskmaster.py b/src/engine/SCons/Taskmaster.py
index 9bd95975..17507a6f 100644
--- a/src/engine/SCons/Taskmaster.py
+++ b/src/engine/SCons/Taskmaster.py
@@ -25,16 +25,19 @@ from __future__ import print_function
 import sys
 
 __doc__ = """
-Generic Taskmaster module for the SCons build engine.
-
-This module contains the primary interface(s) between a wrapping user
-interface and the SCons build engine.  There are two key classes here:
-
+    Generic Taskmaster module for the SCons build engine.
+    =====================================================
+    
+    This module contains the primary interface(s) between a wrapping user
+    interface and the SCons build engine.  There are two key classes here:
+    
     Taskmaster
+    ----------
         This is the main engine for walking the dependency graph and
         calling things to decide what does or doesn't need to be built.
 
     Task
+    ----
         This is the base class for allowing a wrapping interface to
         decide what does or doesn't actually need to be done.  The
         intention is for a wrapping interface to subclass this as
@@ -42,7 +45,7 @@ interface and the SCons build engine.  There are two key classes here:
 
         The canonical example is the SCons native Python interface,
         which has Task subclasses that handle its specific behavior,
-        like printing "`foo' is up to date" when a top-level target
+        like printing "'foo' is up to date" when a top-level target
         doesn't need to be built, and handling the -c option by removing
         targets as its "build" action.  There is also a separate subclass
         for suppressing this output when the -q option is used.
@@ -689,14 +692,14 @@ class Taskmaster(object):
         at node A. The Taskmaster first considers whether node A's
         child B is up-to-date. Then, recursively, node B needs to
         check whether node C is up-to-date. This leaves us with a
-        dependency graph looking like:
+        dependency graph looking like::
 
-                                      Next candidate \
-                                                      \
-        Node A (Pending) --> Node B(Pending) --> Node C (NoState)
-                ^                                     |
-                |                                     |
-                +-------------------------------------+
+                                          Next candidate \
+                                                          \
+            Node A (Pending) --> Node B(Pending) --> Node C (NoState)
+                    ^                                     |
+                    |                                     |
+                    +-------------------------------------+
 
         Now, when the Taskmaster examines the Node C's child Node A,
         it finds that Node A is in the "pending" state. Therefore,
@@ -705,15 +708,14 @@ class Taskmaster(object):
         Pending children indicate that the Taskmaster has potentially
         loop back through a cycle. We say potentially because it could
         also occur when a DAG is evaluated in parallel. For example,
-        consider the following graph:
-
-
-        Node A (Pending) --> Node B(Pending) --> Node C (Pending) --> ...
-                |                                     ^
-                |                                     |
-                +----------> Node D (NoState) --------+
-                                  /
-                  Next candidate /
+        consider the following graph::
+
+            Node A (Pending) --> Node B(Pending) --> Node C (Pending) --> ...
+                    |                                     ^
+                    |                                     |
+                    +----------> Node D (NoState) --------+
+                                      /
+                      Next candidate /
 
         The Taskmaster first evaluates the nodes A, B, and C and
         starts building some children of node C. Assuming, that the
diff --git a/src/engine/SCons/Util.py b/src/engine/SCons/Util.py
index 846d06c9..f4783991 100644
--- a/src/engine/SCons/Util.py
+++ b/src/engine/SCons/Util.py
@@ -231,16 +231,17 @@ class DisplayEngine(object):
     def set_mode(self, mode):
         self.print_it = mode
 
+
 def render_tree(root, child_func, prune=0, margin=[0], visited=None):
     """
     Render a tree of nodes into an ASCII tree view.
-    root - the root node of the tree
-    child_func - the function called to get the children of a node
-    prune - don't visit the same node twice
-    margin - the format of the left margin to use for children of root.
-       1 results in a pipe, and 0 results in no pipe.
-    visited - a dictionary of visited nodes in the current branch if not prune,
-       or in the whole tree if prune.
+
+    :Parameters:
+        - `root`:       the root node of the tree
+        - `child_func`: the function called to get the children of a node
+        - `prune`:      don't visit the same node twice
+        - `margin`:     the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe.
+        - `visited`:    a dictionary of visited nodes in the current branch if not prune, or in the whole tree if prune.
     """
 
     rname = str(root)
@@ -281,14 +282,13 @@ def print_tree(root, child_func, prune=0, showtags=0, margin=[0], visited=None):
     lines directly instead of creating a string representation in memory,
     so that huge trees can be printed.
 
-    root - the root node of the tree
-    child_func - the function called to get the children of a node
-    prune - don't visit the same node twice
-    showtags - print status information to the left of each node line
-    margin - the format of the left margin to use for children of root.
-       1 results in a pipe, and 0 results in no pipe.
-    visited - a dictionary of visited nodes in the current branch if not prune,
-       or in the whole tree if prune.
+    :Parameters:
+        - `root`       - the root node of the tree
+        - `child_func` - the function called to get the children of a node
+        - `prune`      - don't visit the same node twice
+        - `showtags`   - print status information to the left of each node line
+        - `margin`     - the format of the left margin to use for children of root. 1 results in a pipe, and 0 results in no pipe.
+        - `visited`    - a dictionary of visited nodes in the current branch if not prune, or in the whole tree if prune.
     """
 
     rname = str(root)
@@ -1454,19 +1454,20 @@ def make_path_relative(path):
 
 def AddMethod(obj, function, name=None):
     """
-    Adds either a bound method to an instance or the function itself
-    (or an unbound method in Python 2) to a class.
+    Adds either a bound method to an instance or the function itself (or an unbound method in Python 2) to a class.
     If name is ommited the name of the specified function
     is used by default.
-    Example:
-      a = A()
-      def f(self, x, y):
+
+    Example::
+
+        a = A()
+        def f(self, x, y):
         self.z = x + y
-      AddMethod(f, A, "add")
-      a.add(2, 4)
-      print(a.z)
-      AddMethod(lambda self, i: self.l[i], a, "listIndex")
-      print(a.listIndex(5))
+        AddMethod(f, A, "add")
+        a.add(2, 4)
+        print(a.z)
+        AddMethod(lambda self, i: self.l[i], a, "listIndex")
+        print(a.listIndex(5))
     """
     if name is None:
         name = function.__name__
diff --git a/src/engine/SCons/Variables/BoolVariable.py b/src/engine/SCons/Variables/BoolVariable.py
index c005a62d..ce46eda3 100644
--- a/src/engine/SCons/Variables/BoolVariable.py
+++ b/src/engine/SCons/Variables/BoolVariable.py
@@ -2,12 +2,12 @@
 
 This file defines the option type for SCons implementing true/false values.
 
-Usage example:
+Usage example::
 
-  opts = Variables()
-  opts.Add(BoolVariable('embedded', 'build for an embedded system', 0))
-  ...
-  if env['embedded'] == 1:
+    opts = Variables()
+    opts.Add(BoolVariable('embedded', 'build for an embedded system', 0))
+    ...
+    if env['embedded'] == 1:
     ...
 """
 
diff --git a/src/engine/SCons/Variables/EnumVariable.py b/src/engine/SCons/Variables/EnumVariable.py
index 9448ba9a..a9fb1000 100644
--- a/src/engine/SCons/Variables/EnumVariable.py
+++ b/src/engine/SCons/Variables/EnumVariable.py
@@ -3,14 +3,14 @@
 This file defines the option type for SCons allowing only specified
 input-values.
 
-Usage example:
+Usage example::
 
-  opts = Variables()
-  opts.Add(EnumVariable('debug', 'debug output and symbols', 'no',
+    opts = Variables()
+    opts.Add(EnumVariable('debug', 'debug output and symbols', 'no',
                       allowed_values=('yes', 'no', 'full'),
                       map={}, ignorecase=2))
-  ...
-  if env['debug'] == 'full':
+    ...
+    if env['debug'] == 'full':
     ...
 """
 
@@ -69,16 +69,14 @@ def EnumVariable(key, help, default, allowed_values, map={}, ignorecase=0):
 
     'ignorecase' defines the behaviour of the validator:
 
-    If ignorecase == 0, the validator/converter are case-sensitive.
-    If ignorecase == 1, the validator/converter are case-insensitive.
-    If ignorecase == 2, the validator/converter is case-insensitive and
-                        the converted value will always be lower-case.
+        If ignorecase == 0, the validator/converter are case-sensitive.
+        If ignorecase == 1, the validator/converter are case-insensitive.
+        If ignorecase == 2, the validator/converter is case-insensitive and the converted value will always be lower-case.
 
-    The 'validator' tests whether the value is in the list of allowed
-    values. The 'converter' converts input values according to the
-    given 'map'-dictionary (unmapped input values are returned
-    unchanged). 
+    The 'validator' tests whether the value is in the list of allowed values. The 'converter' converts input values
+    according to the given 'map'-dictionary (unmapped input values are returned unchanged).
     """
+
     help = '%s (%s)' % (help, '|'.join(allowed_values))
     # define validator
     if ignorecase >= 1:
diff --git a/src/engine/SCons/Variables/ListVariable.py b/src/engine/SCons/Variables/ListVariable.py
index f2fdc18f..90248676 100644
--- a/src/engine/SCons/Variables/ListVariable.py
+++ b/src/engine/SCons/Variables/ListVariable.py
@@ -7,17 +7,17 @@ separated by comma. After the option has been processed, the option
 value holds either the named list elements, all list elements or no
 list elements at all.
 
-Usage example:
+Usage example::
 
-  list_of_libs = Split('x11 gl qt ical')
+    list_of_libs = Split('x11 gl qt ical')
 
-  opts = Variables()
-  opts.Add(ListVariable('shared',
+    opts = Variables()
+    opts.Add(ListVariable('shared',
                       'libraries to build as shared libraries',
                       'all',
                       elems = list_of_libs))
-  ...
-  for lib in list_of_libs:
+    ...
+    for lib in list_of_libs:
      if lib in env['shared']:
          env.SharedObject(...)
      else:
diff --git a/src/engine/SCons/Variables/PackageVariable.py b/src/engine/SCons/Variables/PackageVariable.py
index 4ab08567..a0ace253 100644
--- a/src/engine/SCons/Variables/PackageVariable.py
+++ b/src/engine/SCons/Variables/PackageVariable.py
@@ -13,18 +13,18 @@ Usage example:
       x11=yes  (will search for the package installation dir)
       x11=/usr/local/X11 (will check this path for existence)
 
-  To replace autoconf's --with-xxx=yyy 
-
-  opts = Variables()
-  opts.Add(PackageVariable('x11',
-                         'use X11 installed here (yes = search some places',
-                         'yes'))
-  ...
-  if env['x11'] == True:
-      dir = ... search X11 in some standard places ...
-      env['x11'] = dir 
-  if env['x11']:
-      ... build with x11 ...
+  To replace autoconf's --with-xxx=yyy ::
+
+      opts = Variables()
+      opts.Add(PackageVariable('x11',
+                             'use X11 installed here (yes = search some places',
+                             'yes'))
+      ...
+      if env['x11'] == True:
+          dir = ... search X11 in some standard places ...
+          env['x11'] = dir
+      if env['x11']:
+          ... build with x11 ...
 """
 
 #
diff --git a/src/engine/SCons/Variables/PathVariable.py b/src/engine/SCons/Variables/PathVariable.py
index e615a531..0ffcbc53 100644
--- a/src/engine/SCons/Variables/PathVariable.py
+++ b/src/engine/SCons/Variables/PathVariable.py
@@ -8,8 +8,7 @@ Arguments to PathVariable are:
   option-name  = name of this option on the command line (e.g. "prefix")
   option-help  = help string for option
   option-dflt  = default value for this option
-  validator    = [optional] validator for option value.  Predefined
-                 validators are:
+  validator    = [optional] validator for option value.  Predefined validators are:
 
                      PathAccept -- accepts any path setting; no validation
                      PathIsDir  -- path must be an existing directory
@@ -25,7 +24,7 @@ Arguments to PathVariable are:
                  and the env is the env to which the Options have been
                  added.
 
-Usage example:
+Usage example::
 
   Examples:
       prefix=/usr/local
@@ -34,8 +33,8 @@ Usage example:
 
   opts = Variables()
   opts.Add(PathVariable('qtdir',
-                      'where the root of Qt is installed',
-                      qtdir, PathIsDir))
+                        'where the root of Qt is installed',
+                        qtdir, PathIsDir))
   opts.Add(PathVariable('qt_includes',
                       'where the Qt includes are installed',
                       '$qtdir/includes', PathIsDirCreate))
diff --git a/src/engine/SCons/Variables/__init__.py b/src/engine/SCons/Variables/__init__.py
index 1fe44351..5b20b300 100644
--- a/src/engine/SCons/Variables/__init__.py
+++ b/src/engine/SCons/Variables/__init__.py
@@ -115,13 +115,13 @@ class Variables(object):
         """
         Add an option.
 
-        key - the name of the variable, or a list or tuple of arguments
-        help - optional help text for the options
-        default - optional default value
-        validator - optional function that is called to validate the option's value
-                    Called with (key, value, environment)
-        converter - optional function that is called to convert the option's value before
-                    putting it in the environment.
+
+        @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):
@@ -141,14 +141,17 @@ class Variables(object):
         Each list element is a tuple/list of arguments to be passed on
         to the underlying method for adding options.
 
-        Example:
-          opt.AddVariables(
+        Example::
+
+            opt.AddVariables(
             ('debug', '', 0),
             ('CC', 'The C compiler'),
             ('VALIDATE', 'An option for testing validation', 'notset',
              validator, None),
             )
+
         """
+
         for o in optlist:
             self._do_add(*o)
 
diff --git a/src/engine/SCons/cpp.py b/src/engine/SCons/cpp.py
index 2e20017d..161f070a 100644
--- a/src/engine/SCons/cpp.py
+++ b/src/engine/SCons/cpp.py
@@ -26,7 +26,6 @@ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
 __doc__ = """
 SCons C Pre-Processor module
 """
-#TODO 2.3 and before has no sorted()
 import SCons.compat
 
 import os
@@ -543,9 +542,11 @@ class PreProcessor(object):
 
         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.
-        """
+
+        where FILE is a #define somewhere else."""
+
         s = t[1]
         while not s[0] in '<"':
             #print("s =", s)
diff --git a/src/engine/SCons/dblite.py b/src/engine/SCons/dblite.py
index 4ef2222d..12b4f766 100644
--- a/src/engine/SCons/dblite.py
+++ b/src/engine/SCons/dblite.py
@@ -40,8 +40,8 @@ except NameError:
 dblite_suffix = '.dblite'
 
 # TODO: Does commenting this out break switching from py2/3?
-# if bytes is not str:
-#     dblite_suffix += '.p3'
+if bytes is not str:
+    dblite_suffix += '.p3'
 tmp_suffix = '.tmp'
 
 
diff --git a/test/Interactive/help.py b/test/Interactive/help.py
index 6020bdec..869876f1 100644
--- a/test/Interactive/help.py
+++ b/test/Interactive/help.py
@@ -57,15 +57,12 @@ scons.send('h\n')
 scons.send('?\n')
 
 help_text = """\
-build [TARGETS]         Build the specified TARGETS and their dependencies.
-                        'b' is a synonym.
-clean [TARGETS]         Clean (remove) the specified TARGETS and their
-                        dependencies.  'c' is a synonym.
+
+build [TARGETS]         Build the specified TARGETS and their dependencies. 'b' is a synonym.
+clean [TARGETS]         Clean (remove) the specified TARGETS and their dependencies.  'c' is a synonym.
 exit                    Exit SCons interactive mode.
-help [COMMAND]          Prints help for the specified COMMAND.  'h' and
-                        '?' are synonyms.
-shell [COMMANDLINE]     Execute COMMANDLINE in a subshell.  'sh' and '!'
-                        are synonyms.
+help [COMMAND]          Prints help for the specified COMMAND.  'h' and '?' are synonyms.
+shell [COMMANDLINE]     Execute COMMANDLINE in a subshell.  'sh' and '!' are synonyms.
 version                 Prints SCons version information.
 """