Merge pull request SCons#4535 from mwichmann/doc/Command

Tweak some things about Command() docs

CHANGES.txt

@@ -70,6 +70,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       on a given page *before* the submodule docs, not after. Also
       tweaked the Util package doc build so it's structured more like the
       other packages (a missed part of the transition when it was split).
+    - Updated manpage description of Command "builder" and function.
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -74,6 +74,7 @@ DOCUMENTATION
 - Update manpage and user guide for Variables usage.
 - Restructured API Docs build so main package contents are listed
   before contents of package submodules.
+- Updated manpage description of Command "builder" and function.
 
 
 

SCons/Builder.py

@@ -387,7 +387,7 @@ def __init__(self,  action = None,
                         target_scanner = None,
                         source_scanner = None,
                         emitter = None,
-                        multi: int = 0,
+                        multi: bool = False,
                         env = None,
                         single_source: bool = False,
                         name = None,

SCons/Environment.py

@@ -2208,52 +2208,44 @@ def Configure(self, *args, **kw):
         return SCons.SConf.SConf(*nargs, **nkw)
 
     def Command(self, target, source, action, **kw):
-        """Builds the supplied target files from the supplied
-        source files using the supplied action.  Action may
-        be any type that the Builder constructor will accept
-        for an action."""
+        """Set up a one-off build command.
+
+        Builds *target* from *source* using *action*, which may be
+        be any type that the Builder factory will accept for an action.
+        Generates an anonymous builder and calls it, to add the details
+        to the build graph. The builder is not named, added to ``BUILDERS``,
+        or otherwise saved.
+
+        Recognizes the :func:`~SCons.Builder.Builder` keywords
+        ``source_scanner``, ``target_scanner``, ``source_factory`` and
+        ``target_factory``.  All other arguments from *kw* are passed on
+        to the builder when it is called.
+        """
+        # Build a kwarg dict for the builder construction
         bkw = {
             'action': action,
             'target_factory': self.fs.Entry,
             'source_factory': self.fs.Entry,
         }
-        # source scanner
-        try:
-            bkw['source_scanner'] = kw['source_scanner']
-        except KeyError:
-            pass
-        else:
-            del kw['source_scanner']
-
-        # target scanner
-        try:
-            bkw['target_scanner'] = kw['target_scanner']
-        except KeyError:
-            pass
-        else:
-            del kw['target_scanner']
-
-        # source factory
-        try:
-            bkw['source_factory'] = kw['source_factory']
-        except KeyError:
-            pass
-        else:
-            del kw['source_factory']
 
-        # target factory
-        try:
-            bkw['target_factory'] = kw['target_factory']
-        except KeyError:
-            pass
-        else:
-            del kw['target_factory']
+        # Recognize these kwargs for the builder construction and take
+        # them out of the args for the subsequent builder call.
+        for arg in [
+            'source_scanner',
+            'target_scanner',
+            'source_factory',
+            'target_factory',
+        ]:
+            try:
+                bkw[arg] = kw.pop(arg)
+            except KeyError:
+                pass
 
         bld = SCons.Builder.Builder(**bkw)
         return bld(self, target, source, **kw)
 
     def Depends(self, target, dependency):
-        """Explicity specify that 'target's depend on 'dependency'."""
+        """Explicity specify that *target* depends on *dependency*."""
         tlist = self.arg2nodes(target, self.fs.Entry)
         dlist = self.arg2nodes(dependency, self.fs.Entry)
         for t in tlist:
@@ -2281,7 +2273,7 @@ def PyPackageDir(self, modulename):
         return self.fs.PyPackageDir(s)
 
     def NoClean(self, *targets):
-        """Tags a target so that it will not be cleaned by -c"""
+        """Tag target(s) so that it will not be cleaned by -c."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))
@@ -2290,7 +2282,7 @@ def NoClean(self, *targets):
         return tlist
 
     def NoCache(self, *targets):
-        """Tags a target so that it will not be cached"""
+        """Tag target(s) so that it will not be cached."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))

SCons/Environment.xml

@@ -1125,15 +1125,16 @@ wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
 <builder name="Command">
 <summary>
 <para>
-The &b-Command; "Builder" is actually
-a function that looks like a Builder,
-but takes a required third argument, which is the
-action to take to construct the target
-from the source, used for "one-off" builds
-where a full builder is not needed.
-Thus it does not follow the builder
-calling rules described at the start of this section.
-See instead the &f-link-Command; function description
+There is actually no Builder named &Command;,
+rather the term "Command Builder" refers to
+a function which, on each call, creates and calls
+an anonymous Builder.
+This is useful for "one-off" builds
+where a full Builder is not needed.
+Since the anonymous Builder is never hooked
+into the standard Builder framework,
+an Action must always be specfied.
+See the &f-link-Command; function description
 for the calling syntax and details.
 </para>
 </summary>
@@ -1145,49 +1146,69 @@ for the calling syntax and details.
 </arguments>
 <summary>
 <para>
-Executes a specific <parameter>action</parameter>
-(or list of actions)
-to build a <parameter>target</parameter> file or files
-from a <parameter>source</parameter> file or files.
-This is more convenient
-than defining a separate Builder object
-for a single special-case build.
+Creates an anonymous builder and calls it,
+thus recording <parameter>action</parameter>
+to build <parameter>target</parameter>
+from <parameter>source</parameter>
+into the dependency tree.
+This can be more convenient for a single special-case build
+than having to define and add a new named Builder.
 </para>
 
 <para>
 The
-&Command; function accepts
-<parameter>source_scanner</parameter>,
-<parameter>target_scanner</parameter>,
-<parameter>source_factory</parameter>, and
-<parameter>target_factory</parameter>
-keyword arguments. These arguments can
-be used to specify
-a Scanner object
-that will be used to apply a custom
-scanner for a source or target.
+&Command; function accepts the
+<parameter>source_scanner</parameter> and
+<parameter>target_scanner</parameter>
+keyword arguments which are used to specify
+custom scanners for the specified sources or targets.
+The value must be a Scanner object.
 For example, the global
 <literal>DirScanner</literal>
 object can be used
 if any of the sources will be directories
 that must be scanned on-disk for
 changes to files that aren't
-already specified in other Builder of function calls.
-The <parameter>*_factory</parameter> arguments take a factory function that
-&Command; will use to turn any sources or targets
-specified as strings into SCons Nodes.
+already specified in other Builder or function calls.
+</para>
+
+<para>
+The
+&Command; function also accepts the
+<parameter>source_factory</parameter> and
+<parameter>target_factory</parameter>
+keyword arguments which are used to specify
+factory functions to create &SCons; Nodes
+from any sources or targets specified as strings.
+If any sources or targets are already Node objects,
+they are not further transformed even if
+a factory is specified for them.
+The default for each is the &Entry; factory.
+</para>
+
+<para>
+These four arguments, if given, are used
+in the creation of the Builder.
+Other Builder-specific keyword arguments
+are not recognized as such.
 See the manpage section "Builder Objects"
 for more information about how these
 arguments work in a Builder.
 </para>
 
 <para>
-Any other keyword arguments specified override any
-same-named existing construction variables.
+Any remaining keyword arguments are passed on to the
+generated builder when it is called,
+and behave as described in the manpage section "Builder Methods",
+in short:
+recognized arguments have their specified meanings,
+while the rest are used to override
+any same-named existing &consvars;
+from the &consenv;.
 </para>
 
 <para>
-An action can be an external command,
+<parameter>action</parameter> can be an external command,
 specified as a string,
 or a callable &Python; object;
 see the manpage section "Action Objects"
@@ -1649,7 +1670,7 @@ would supply a string as a directory name
 to a Builder method or function.
 Directory Nodes have attributes and methods
 that are useful in many situations;
-see manpage section "File and Directory Nodes"
+see manpage section "Filesystem Nodes"
 for more information.
 </para>
 </summary>
@@ -1849,7 +1870,7 @@ would supply a string as a file name
 to a Builder method or function.
 File Nodes have attributes and methods
 that are useful in many situations;
-see manpage section "File and Directory Nodes"
+see manpage section "Filesystem Nodes"
 for more information.
 </para>
 </summary>

doc/generated/builders.gen

@@ -39,15 +39,16 @@ env.CFile(target='bar', source='bar.y')
     <term><function>Command</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>Command</methodname>()</term>
     <listitem><para>
-The &b-Command; "Builder" is actually
-a function that looks like a Builder,
-but takes a required third argument, which is the
-action to take to construct the target
-from the source, used for "one-off" builds
-where a full builder is not needed.
-Thus it does not follow the builder
-calling rules described at the start of this section.
-See instead the &f-link-Command; function description
+There is actually no Builder named &Command;,
+rather the term "Command Builder" refers to
+a function which, on each call, creates and calls
+an anonymous Builder.
+This is useful for "one-off" builds
+where a full Builder is not needed.
+Since the anonymous Builder is never hooked
+into the standard Builder framework,
+an Action must always be specfied.
+See the &f-link-Command; function description
 for the calling syntax and details.
 </para>
 </listitem>