Skip to content

Commit

Permalink
Doc: use consistent repeated-args syntax [skip appveyor]
Browse files Browse the repository at this point in the history
For now, want to keep the "key=value, ..." form for Functions/Method
signatures instead of using **kwargs, since that terminology hasn't
been introduced.  May switch signatures later, but if so, do them all,
let's not be piecemeal.

Signed-off-by: Mats Wichmann <mats@linux.com>
  • Loading branch information
mwichmann committed Aug 3, 2024
1 parent c7a3c96 commit a5c85cf
Show file tree
Hide file tree
Showing 4 changed files with 60 additions and 42 deletions.
2 changes: 2 additions & 0 deletions CHANGES.txt
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER
- Switch SCons build to use setuptools' supported version fetcher from
the old homegrown one.
- Improve wording of manpage "Functions and Environment Methods" section.
Make doc function signature style more consistent - tweaks to AddOption,
DefaultEnvironment and Tool,.


RELEASE 4.8.0 - Sun, 07 Jul 2024 17:22:20 -0700
Expand Down
72 changes: 41 additions & 31 deletions SCons/Defaults.xml
Original file line number Diff line number Diff line change
Expand Up @@ -729,43 +729,53 @@ searching the repositories.

<scons_function name="DefaultEnvironment">
<arguments signature="global">
([**kwargs])
([key=value, ...])
</arguments>
<summary>
<para>
Instantiates and returns the global &consenv; object.
This environment is used internally by SCons
when it executes many of the global functions listed in this section
(that is, those not called as methods of a specific &consenv;).
The &defenv; is a singleton:
the keyword arguments are used only on the first call;
on subsequent calls the already-constructed object is returned
The <firstterm>&DefEnv;</firstterm> is used internally by &SCons;
when executing a global function
or the global form of a Builder method
that requires access to a &consenv;.
</para>

<para>
On the first call,
arguments are interpreted as for the &f-link-Environment; function.
The &DefEnv; is a singleton;
subsequent calls to &f-DefaultEnvironment; return
the already-constructed object,
and any keyword arguments are silently ignored.
The &defenv; can still be modified after instantiation
in the same way as any other &consenv;.
The &defenv; is independent:
modifying it has no effect on any other &consenv;
constructed by an &f-link-Environment; or &f-link-Clone; call.
</para>

<para>
It is not mandatory to call &f-DefaultEnvironment;:
the &defenv; is instantiated automatically when the
build phase begins if this function has not been called;
however calling it explicitly gives the opportunity to
affect and examine the contents of the &defenv;.
Instantiation happens even if no build instructions
appar to use it, as there are internal uses.
If there are no uses in the project &SConscript; files,
a small performance gain may be seen by calling
&f-DefaultEnvironment; with an empty tools list,
thus avoiding that part of the initialization cost.
This is mainly of interest in testing when &scons; is
launched repeatedly in a short time period:
</para>
<example_commands>
DefaultEnvironment(tools=[])
</example_commands>

<para>
The &DefEnv; can be modified after instantiation,
similar to other &consenvs;,
although some &consenv; methods may be unavailable.
Modifying the &DefEnv; has no effect on any other &consenv;,
either existing or newly constructed.
</para>

<para>
It is not necessary to explcitly call &f-DefaultEnvironment;.
&SCons; instantiates the &defenv; automatically when the
build phase begins, if has not already been done.
However, calling it explicitly provides the opportunity to
affect and examine its contents.
Instantiation occurs even if nothing in the build system
appars to use it, due to internal uses.
</para>

<para>
If the project &SConscript; files do not use global functions or Builders,
a small performance gain may be achieved by calling
&f-DefaultEnvironment; with an empty tools list
(<userinput>DefaultEnvironment(tools=[])</userinput>).
This avoids the tool initialization cost for the &DefEnv;,
which is mainly of interest in the test suite
where &scons; is launched repeatedly in a short time period.
</para>
</summary>
</scons_function>

Expand Down
2 changes: 1 addition & 1 deletion SCons/Environment.xml
Original file line number Diff line number Diff line change
Expand Up @@ -3489,7 +3489,7 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)

<scons_function name="Tool">
<arguments>
(name, [toolpath, **kwargs])
(name, [toolpath, key=value, ...])
</arguments>
<summary>

Expand Down
26 changes: 16 additions & 10 deletions SCons/Script/Main.xml
Original file line number Diff line number Diff line change
Expand Up @@ -27,18 +27,25 @@ This file is processed by the bin/SConsDoc.py module.

<scons_function name="AddOption">
<arguments signature="global">
(arguments)
(opt_str, ..., attr=value, ...)
</arguments>
<summary>
<para>
Adds a local (project-specific) command-line option.
<parameter>arguments</parameter>
are the same as those supported by the <function>add_option</function>
method in the standard Python library module <systemitem>optparse</systemitem>,
with a few additional capabilities noted below.
See the documentation for
<systemitem>optparse</systemitem>
One or more <parameter>opt_str</parameter> values are
the strings representing how the option can be called,
while the keyword arguments define attributes of the option.
For the most part these are the same as for the
<function>OptionParser.add_option</function>
method in the standard Python library module
<systemitem>optparse</systemitem>,
but with a few additional capabilities noted below.
See the
<ulink url="https://docs.python.org/3/library/optparse.html">
optparse documentation</ulink>
for a thorough discussion of its option-processing capabities.
All options added through &f-AddOption; are placed
in a special "Local Options" option group.
</para>

<para>
Expand All @@ -49,10 +56,9 @@ method, &f-AddOption;
allows setting the
<parameter>nargs</parameter>
keyword value to
a string consisting of a question mark
(<literal>'?'</literal>)
a string <literal>'?'</literal> (question mark)
to indicate that the option argument for
that option string is optional.
that option string may be omitted.
If the option string is present on the
command line but has no matching option
argument, the value of the
Expand Down

0 comments on commit a5c85cf

Please sign in to comment.