summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWilliam Deegan <bill@baddogconsulting.com>2017-09-01 02:57:51 (GMT)
committerWilliam Deegan <bill@baddogconsulting.com>2017-09-01 02:57:51 (GMT)
commit29e9530300108c91ba446921bcdc95595a445245 (patch)
tree7f2a3a36201d9548ce6f62e742a467e07b7d8422
parent37dfc19d9bb694d80c1bc97d79e519a6d90bcaba (diff)
downloadSCons-29e9530300108c91ba446921bcdc95595a445245.zip
SCons-29e9530300108c91ba446921bcdc95595a445245.tar.gz
SCons-29e9530300108c91ba446921bcdc95595a445245.tar.bz2
Fix many epydoc warnings
-rw-r--r--src/engine/SCons/Action.py29
-rw-r--r--src/engine/SCons/Builder.py23
-rw-r--r--src/engine/SCons/Conftest.py42
-rw-r--r--src/engine/SCons/Environment.py3
-rw-r--r--src/engine/SCons/Errors.py85
-rw-r--r--src/engine/SCons/Memoize.py4
-rw-r--r--src/engine/SCons/Node/FS.py30
-rw-r--r--src/engine/SCons/SConf.py6
-rw-r--r--src/engine/SCons/Scanner/LaTeX.py22
-rw-r--r--src/engine/SCons/Scanner/__init__.py6
-rw-r--r--src/engine/SCons/Script/Interactive.py19
-rw-r--r--src/engine/SCons/Taskmaster.py46
-rw-r--r--src/engine/SCons/Util.py51
-rw-r--r--src/engine/SCons/Variables/BoolVariable.py10
-rw-r--r--src/engine/SCons/Variables/EnumVariable.py24
-rw-r--r--src/engine/SCons/Variables/ListVariable.py12
-rw-r--r--src/engine/SCons/Variables/PackageVariable.py24
-rw-r--r--src/engine/SCons/Variables/PathVariable.py9
-rw-r--r--src/engine/SCons/Variables/__init__.py21
-rw-r--r--src/engine/SCons/cpp.py7
-rw-r--r--src/engine/SCons/dblite.py4
-rw-r--r--test/Interactive/help.py13
22 files changed, 251 insertions, 239 deletions
diff --git a/src/engine/SCons/Action.py b/src/engine/SCons/Action.py
index d6fe30b..b44088b 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 21f1b4a..afc2cf0 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 4db7e06..abaf00d 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 6a127db..42b28e6 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 1df8cb9..2ba007c 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 9774bdd..5bdcf42 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 c31ac6c..684f0d1 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 889af4a..48eed8e 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 e5abb0c..5800443 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 c0f1a93..f7828ab 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 6be7b27..cc4f23c 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 9bd9597..17507a6 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 846d06c..f478399 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 c005a62..ce46eda 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 9448ba9..a9fb100 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 f2fdc18..9024867 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 4ab0856..a0ace25 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 e615a53..0ffcbc5 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 1fe4435..5b20b30 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 2e20017..161f070 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 4ef2222..12b4f76 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 6020bde..869876f 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.
"""