Merge pull request SCons#4583 from mwichmann/doc/consistent-signatures

Doc: use consistent repeated-args syntax

CHANGES.txt

@@ -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

RELEASE.txt

@@ -63,6 +63,9 @@ DOCUMENTATION
 -------------
 
 - Improve wording of manpage "Functions and Environment Methods" section.
+- Make doc function signature style more consistent - tweaks to AddOption,
+  DefaultEnvironment and Tool,.
+
 
 DEVELOPMENT
 -----------

SCons/Defaults.xml

@@ -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 explicitly 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>
 

SCons/Environment.xml

@@ -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>
 

SCons/Script/Main.xml

@@ -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>
@@ -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