From 92f12d78cb46100115812f83b2d1e6f2a67163ae Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 21 Oct 2022 09:17:37 -0600 Subject: Minor doc update for Value nodes [skip appveyor] Add a "changed in version 4.0" for a past change. Fiddled some docstrings. Tweaked docstring for env.Tool as well - proximity in the files was the motivation (it's just above in Environment.xml) - trying to get to a consistent added/changed notation format, following the Sphinx docstring directive style. Signed-off-by: Mats Wichmann --- SCons/Environment.py | 15 +++++++++++---- SCons/Environment.xml | 36 ++++++++++++++++++++++-------------- SCons/Node/Python.py | 15 +++++++++++---- SCons/Node/__init__.py | 10 +++++----- 4 files changed, 49 insertions(+), 27 deletions(-) diff --git a/SCons/Environment.py b/SCons/Environment.py index e458f25..293447f 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -1897,6 +1897,11 @@ class Base(SubstitutionEnvironment): return self.fs.Dir(self.subst(tp)).srcnode().get_abspath() def Tool(self, tool, toolpath=None, **kwargs) -> SCons.Tool.Tool: + """Find and run tool module *tool*. + + .. versionchanged:: 4.2 + returns the tool module rather than ``None``. + """ if is_String(tool): tool = self.subst(tool) if toolpath is None: @@ -2335,7 +2340,10 @@ class Base(SubstitutionEnvironment): return [self.subst(arg)] def Value(self, value, built_value=None, name=None): - """ + """Return a Value (Python expression) node. + + .. versionchanged:: 4.0 + the *name* parameter was added. """ return SCons.Node.Python.ValueWithMemo(value, built_value, name) @@ -2344,9 +2352,8 @@ class Base(SubstitutionEnvironment): src_dir = self.arg2nodes(src_dir, self.fs.Dir)[0] self.fs.VariantDir(variant_dir, src_dir, duplicate) - def FindSourceFiles(self, node='.'): - """ returns a list of all source files. - """ + def FindSourceFiles(self, node='.') -> list: + """Return a list of all source files.""" node = self.arg2nodes(node, self.fs.Entry)[0] sources = [] diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 2c5d563..2e06b1e 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -3311,6 +3311,12 @@ appended to the &cv-link-TOOLS; +Changed in version 4.2: +&f-env-Tool; now returns the tool object, +previously it did not return (i.e. returned None). + + + Examples: @@ -3347,12 +3353,6 @@ msvctool(env) # adds 'msvc' to the TOOLS variable gltool = Tool('opengl', toolpath = ['tools']) gltool(env) # adds 'opengl' to the TOOLS variable - - -Changed in &SCons; 4.2: &f-env-Tool; now returns -the tool object, previously it did not return -(i.e. returned None). - @@ -3373,10 +3373,6 @@ will be rebuilt. files are up-to-date.) When using timestamp source signatures, Value Nodes' timestamps are equal to the system time when the Node is created. -name can be provided as an alternative name -for the resulting Value node; this is advised -if the value parameter can't be converted to -a string. @@ -3396,6 +3392,18 @@ method that will return the built value of the Node. +The optional name parameter can be provided as an +alternative name for the resulting Value node; +this is advised if the value parameter +cannot be converted to a string. + + + +Changed in version 4.0: +the name parameter was added. + + + Examples: @@ -3415,8 +3423,8 @@ prefix = ARGUMENTS.get('prefix', '/usr/local') # Attach a .Config() builder for the above function action # to the construction environment. -env['BUILDERS']['Config'] = Builder(action = create) -env.Config(target = 'package-config', source = Value(prefix)) +env['BUILDERS']['Config'] = Builder(action=create) +env.Config(target='package-config', source=Value(prefix)) def build_value(target, source, env): # A function that "builds" a Python Value by updating @@ -3429,8 +3437,8 @@ input = env.Value('after') # Attach a .UpdateValue() builder for the above function # action to the construction environment. -env['BUILDERS']['UpdateValue'] = Builder(action = build_value) -env.UpdateValue(target = Value(output), source = Value(input)) +env['BUILDERS']['UpdateValue'] = Builder(action=build_value) +env.UpdateValue(target=Value(output), source=Value(input)) diff --git a/SCons/Node/Python.py b/SCons/Node/Python.py index 80d2762..57416ef 100644 --- a/SCons/Node/Python.py +++ b/SCons/Node/Python.py @@ -75,8 +75,13 @@ class ValueBuildInfo(SCons.Node.BuildInfoBase): class Value(SCons.Node.Node): - """A class for Python variables, typically passed on the command line - or generated by a script, but not from a file or some other source. + """A Node class for values represented by Python expressions. + + Values are typically passed on the command line or generated + by a script, but not from a file or some other source. + + .. versionchanged:: 4.0 + the *name* parameter was added. """ NodeInfo = ValueNodeInfo @@ -165,8 +170,10 @@ class Value(SCons.Node.Node): def ValueWithMemo(value, built_value=None, name=None): - """ - Memoized Value() node factory. + """Memoized :class:`Value` node factory. + + .. versionchanged:: 4.0 + the *name* parameter was added. """ global _memo_lookup_map diff --git a/SCons/Node/__init__.py b/SCons/Node/__init__.py index ec742a6..bb09868 100644 --- a/SCons/Node/__init__.py +++ b/SCons/Node/__init__.py @@ -685,8 +685,8 @@ class Node(object, metaclass=NoSlotsPyPy): """Try to retrieve the node's content from a cache This method is called from multiple threads in a parallel build, - so only do thread safe stuff here. Do thread unsafe stuff in - built(). + so only do thread safe stuff here. Do thread unsafe stuff + in :meth:`built`. Returns true if the node was successfully retrieved. """ @@ -743,12 +743,12 @@ class Node(object, metaclass=NoSlotsPyPy): """Actually build the node. This is called by the Taskmaster after it's decided that the - Node is out-of-date and must be rebuilt, and after the prepare() - method has gotten everything, uh, prepared. + Node is out-of-date and must be rebuilt, and after the + :meth:`prepare` method has gotten everything, uh, prepared. This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff - in built(). + in :meth:`built`. """ try: -- cgit v0.12