From b3f2e6671a3cfa34b9e73f2ca20eac1ef9d409a0 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 26 Apr 2020 10:37:09 -0600 Subject: Exports doc fixes [ci skip] Fix a couple of typos discoverted by sider. Update doc entries in the (shared) function descriptions of Export, Import and Return (Environment.xml) Signed-off-by: Mats Wichmann --- doc/user/hierarchy.xml | 4 +- src/engine/SCons/Script/SConscript.xml | 82 +++++++++++++++++----------------- 2 files changed, 44 insertions(+), 42 deletions(-) diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index b54e2a5..11a68f9 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -563,7 +563,7 @@ Export('env', 'debug') - Beacuse a Python identifier cannot contain spaces, + Because a Python identifier cannot contain spaces, &Export; assumes a string containing spaces is multiple variable names to export and splits it for you: @@ -721,7 +721,7 @@ env.Program('prog', ['prog.c']) - &Import; prefers a local defintion to a global one, + &Import; prefers a local definition to a global one, so that if there is a global export of foo, and the calling SConscript has exported foo to this SConscript, diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml index a1e0129..d42fdac 100644 --- a/src/engine/SCons/Script/SConscript.xml +++ b/src/engine/SCons/Script/SConscript.xml @@ -26,7 +26,7 @@ See its __doc__ string for a discussion of the format. -(targets) +(targets...) @@ -163,21 +163,23 @@ is used if no value is specified. -(vars) +([vars...], [key=value...]) -This tells -&scons; -to export a list of variables from the current -SConscript file to all other SConscript files. -The exported variables are kept in a global collection, -so subsequent calls to +Exports a list of variables from the current +SConscript file to a global collection where they can be +imported by any other SConscript file. +vars are keys used to +look up the value, so they must be +string represenations of the names of the variables +to be exported. +Subsequent calls to &f-Export; -will over-write previous exports that have the same name. +will over-write any previous exports that have the same name. Multiple variable names can be passed to &f-Export; -as separate arguments or as a list. +as separate arguments or as words in a space-separated string. Keyword arguments can be used to provide names and their values. A dictionary can be used to map variables to a different name when exported. Both local variables and global variables can be exported. @@ -214,7 +216,7 @@ function supports an argument that makes it easier to to export a variable or set of variables to a single SConscript file. See the description of the -&f-SConscript; +&f-link-SConscript; function, below. @@ -270,26 +272,25 @@ message. -(vars) +(vars...) -This tells -&scons; -to import a list of variables into the current SConscript file. This -will import variables that were exported with -&f-Export; -or in the +Imports a list of variables into the current SConscript file. +The variables must be string representations of variable +names which have been previously exported either by the +&f-link-Export; function or by the exports argument to &f-link-SConscript;. Variables exported by &f-SConscript; -have precedence. +take precedence. Multiple variable names can be passed to &f-Import; -as separate arguments or as a list. The variable "*" can be used -to import all variables. +as separate arguments or as words in a space-separated string. +The wildcard "*" can be used to import all +available variables. @@ -311,32 +312,35 @@ Import("*") -By default, -this stops processing the current SConscript -file and returns to the calling SConscript file -the values of the variables named in the +Return to the calling SConscript, optionally +returning the values of variables named in the vars string arguments. Multiple strings contaning variable names may be passed to -&f-Return;. -Any strings that contain white space +&f-Return;. A string containing white space +is split into words, which are considered individual +variable names. +Returns a tuple of values, or value that evaluates +False +if no vars were specified. +By default &Return; stops processing the current SConscript +and returns immediately. The optional stop= keyword argument may be set to a false value to continue processing the rest of the SConscript file after the &f-Return; -call. -This was the default behavior prior to SCons 0.98. +call (this was the default behavior prior to SCons 0.98.) However, the values returned are still the values of the variables in the named vars at the point &f-Return; -is called. +was called. @@ -434,17 +438,15 @@ SConscript(dirs=['sub1', 'sub2'], name='MySConscript') The optional exports -argument provides a list of variable names or a dictionary of -named values to export to the -script(s). -These variables are locally exported only to the specified -script(s), -and do not affect the global pool of variables used by the -&f-Export; +argument provides a list of string representations of +variable names or a dictionary of named values to export. +These variables are locally exported only to the called +SConscript files +and do not affect the global pool of variables managed by the +&f-link-Export; function. -The subsidiary -script(s) +The subsidiary SConscript files must use the &f-link-Import; function to import the variables. @@ -482,7 +484,7 @@ argument is interpreted relative to the directory of the calling file. See the description of the &f-VariantDir; -function below for additional details and restrictions. +function for additional details and restrictions. -- cgit v0.12