Merge pull request #4355 from mwichmann/doc/manstuff

Doc fiddling - Alias, Action, Decider  [skip appveyor]

6 files changed, 134 insertions, 91 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 5ad76b8de..6e8e6778e 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -25,6 +25,13 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       Only used in msvs.py. Use base64.decodebytes instead.
     - SCons test runner now uses pathlib to normalize and compare paths
       to test files.
+    - Minor doc fixes: signature of Alias() now matches implementation
+      to avoid problem if kwargs used; case of Alias with no targets is
+      mentioned in text (was already shown in example); now mention that
+      Action([item]) does not return a ListAction - previously implied
+      that if arg was a list, a ListAction was *always* returned; mention
+      default Decider and sort the names of available decider functions,
+      and add a version marking.  Minor fiddling with Alias.py docstrings.
 
 
 RELEASE 4.5.2 -  Sun, 21 Mar 2023 14:08:29 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index bafda4777..5cef73156 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -57,9 +57,10 @@ PACKAGING
 DOCUMENTATION
 -------------
 
-- List any significant changes to the documentation (not individual
-  typo fixes, even if they're mentioned in src/CHANGES.txt to give
-  the contributor credit)
+- Aligned manpage signature for Alias function to match implementation -
+  if the previous *targets* parameter had been used as a keyword argument,
+  the results would be incorrect (does not apply to positional argument
+  usage, which had no problem).
 
 DEVELOPMENT
 -----------
diff --git a/SCons/Action.py b/SCons/Action.py
index 3f1a24ecc..fcc6f3f0e 100644
--- a/SCons/Action.py
+++ b/SCons/Action.py
@@ -148,9 +148,8 @@ def default_exitstatfunc(s):
 strip_quotes = re.compile(r'^[\'"](.*)[\'"]$')
 
 
-def _callable_contents(obj):
-    """Return the signature contents of a callable Python object.
-    """
+def _callable_contents(obj) -> bytearray:
+    """Return the signature contents of a callable Python object."""
     try:
         # Test if obj is a method.
         return _function_contents(obj.__func__)
@@ -170,7 +169,7 @@ def _callable_contents(obj):
                 return _function_contents(obj)
 
 
-def _object_contents(obj):
+def _object_contents(obj) -> bytearray:
     """Return the signature contents of any Python object.
 
     We have to handle the case where object contains a code object
@@ -210,8 +209,10 @@ def _object_contents(obj):
                         # the best we can.
                         return bytearray(repr(obj), 'utf-8')
 
+# TODO: docstrings for _code_contents and _function_contents
+#   do not render well with Sphinx. Consider reworking.
 
-def _code_contents(code, docstring=None):
+def _code_contents(code, docstring=None) -> bytearray:
     r"""Return the signature contents of a code object.
 
     By providing direct access to the code object of the
@@ -223,7 +224,7 @@ def _code_contents(code, docstring=None):
     recompilations from moving a Python function.
 
     See:
-      - https://docs.python.org/2/library/inspect.html
+      - https://docs.python.org/3/library/inspect.html
       - http://python-reference.readthedocs.io/en/latest/docs/code/index.html
 
     For info on what each co\_ variable provides
@@ -243,7 +244,6 @@ def _code_contents(code, docstring=None):
     co_code     - Returns a string representing the sequence of bytecode instructions.
 
     """
-
     # contents = []
 
     # The code contents depends on the number of local variables
@@ -281,8 +281,9 @@ def _code_contents(code, docstring=None):
     return contents
 
 
-def _function_contents(func):
-    """
+def _function_contents(func) -> bytearray:
+    """Return the signature contents of a function.
+
     The signature is as follows (should be byte/chars):
     < _code_contents (see above) from func.__code__ >
     ,( comma separated _object_contents for function argument defaults)
@@ -293,11 +294,7 @@ def _function_contents(func):
       - func.__code__     - The code object representing the compiled function body.
       - func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value
       - func.__closure__  - None or a tuple of cells that contain bindings for the function's free variables.
-
-    :Returns:
-      Signature contents of a function. (in bytes)
     """
-
     contents = [_code_contents(func.__code__, func.__doc__)]
 
     # The function contents depends on the value of defaults arguments
@@ -439,16 +436,13 @@ def _do_create_keywords(args, kw):
 
 
 def _do_create_action(act, kw):
-    """This is the actual "implementation" for the
-    Action factory method, below.  This handles the
-    fact that passing lists to Action() itself has
-    different semantics than passing lists as elements
-    of lists.
-
-    The former will create a ListAction, the latter
-    will create a CommandAction by converting the inner
-    list elements to strings."""
+    """The internal implementation for the Action factory method.
 
+    This handles the fact that passing lists to :func:`Action` itself has
+    different semantics than passing lists as elements of lists.
+    The former will create a :class:`ListAction`, the latter will create a
+    :class:`CommandAction by converting the inner list elements to strings.
+    """
     if isinstance(act, ActionBase):
         return act
 
@@ -491,13 +485,22 @@ def _do_create_action(act, kw):
     return None
 
 
-def _do_create_list_action(act, kw):
-    """A factory for list actions.  Convert the input list into Actions
-    and then wrap them in a ListAction."""
+# TODO: from __future__ import annotations once we get to Python 3.7 base,
+#   to avoid quoting the defined-later classname
+def _do_create_list_action(act, kw) -> "ListAction":
+    """A factory for list actions.
+
+    Convert the input list *act* into Actions and then wrap them in a
+    :class:`ListAction`. If *act* has only a single member, return that
+    member, not a *ListAction*. This is intended to allow a contained
+    list to specify a command action without being processed into a
+    list action.
+    """
     acts = []
     for a in act:
         aa = _do_create_action(a, kw)
-        if aa is not None: acts.append(aa)
+        if aa is not None:
+            acts.append(aa)
     if not acts:
         return ListAction([])
     elif len(acts) == 1:
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index f87e88393..2b4c4af7e 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -351,9 +351,9 @@ to be performed
 after the specified
 <parameter>target</parameter>
 has been built.
-The specified action(s) may be
+<parameter>action</parameter> may be
 an Action object, or anything that
-can be converted into an Action object
+can be converted into an Action object.
 See the manpage section "Action Objects"
 for a complete explanation.
 </para>
@@ -364,6 +364,13 @@ the action may be called multiple times,
 once after each action that generates
 one or more targets in the list.
 </para>
+
+<example_commands>
+foo = Program('foo.c')
+# remove execute permission from binary:
+AddPostAction(foo, Chmod('$TARGET', "a-x"))
+</example_commands>
+
 </summary>
 </scons_function>
 
@@ -379,9 +386,9 @@ to be performed
 before the specified
 <parameter>target</parameter>
 is built.
-The specified action(s) may be
+<parameter>action</parameter> may be
 an Action object, or anything that
-can be converted into an Action object
+can be converted into an Action object.
 See the manpage section "Action Objects"
 for a complete explanation.
 </para>
@@ -426,21 +433,35 @@ file into an object file.
 
 <scons_function name="Alias">
 <arguments>
-(alias, [targets, [action]])
+(alias, [source, [action]])
 </arguments>
 <summary>
 <para>
-Creates one or more phony targets that
-expand to one or more other targets.
-An optional
+Creates a phony target (or targets) that
+can be used as references to zero or more other targets,
+as specified by the optional <parameter>source</parameter>
+parameter.
+<parameter>alias</parameter> and
+<parameter>source</parameter>
+may each be a string or Node object,
+or a list of strings or Node objects;
+if Nodes are used for
+<parameter>alias</parameter>
+they must be Alias nodes.
+The optional
 <parameter>action</parameter>
-(command)
-or list of actions
-can be specified that will be executed
+parameter specifies an action or list of actions
+that will be executed
 whenever the any of the alias targets are out-of-date.
-Returns the Node object representing the alias,
-which exists outside of any file system.
-This Node object, or the alias name,
+</para>
+
+<para>
+Returns a list of Alias Node objects representing the alias(es),
+which exist outside of any physical file system.
+</para>
+
+<para>
+The alias name, or an Alias Node object,
 may be used as a dependency of any other target,
 including another alias.
 &f-Alias;
@@ -593,7 +614,7 @@ giving an easy way to enter multiple macros in one addition.
 Use an <literal>=</literal> to specify a valued macro.</para>
 </listitem>
 <listitem>
-<para>A tuple is treated as a valued macro. 
+<para>A tuple is treated as a valued macro.
 Use the value <constant>None</constant> if the macro should not have a value.
 It is an error to supply more than two elements in such a tuple.</para>
 </listitem>
@@ -1238,8 +1259,8 @@ so you normally don't need to create directories by hand.
 </arguments>
 <summary>
 <para>
-Creates a Configure object for integrated
-functionality similar to GNU autoconf.
+Creates a &Configure; object for integrated
+functionality similar to GNU <command>autoconf</command>.
 See the manpage section "Configure Contexts"
 for a complete explanation of the arguments and behavior.
 </para>
@@ -1265,50 +1286,24 @@ that will be applied:
 <para>
 <variablelist>
 <varlistentry>
-<term><literal>"timestamp-newer"</literal></term>
-<listitem>
-<para>
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's timestamp is newer than the target file's timestamp.
-This is the behavior of the classic Make utility,
-and
-<literal>make</literal>
-can be used a synonym for
-<literal>timestamp-newer</literal>.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><literal>"timestamp-match"</literal></term>
-<listitem>
-<para>
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's timestamp is different than the
-timestamp recorded the last time the target was built.
-This provides behavior very similar to the classic Make utility
-(in particular, files are not opened up so that their
-contents can be checksummed)
-except that the target will also be rebuilt if a
-dependency file has been restored to a version with an
-<emphasis>earlier</emphasis>
-timestamp, such as can happen when restoring files from backup archives.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
 <term><literal>"content"</literal></term>
 <listitem>
 <para>
 Specifies that a target shall be considered out of date and rebuilt
 if the dependency's content has changed since the last time
 the target was built,
-as determined be performing an checksum
-on the dependency's contents
+as determined by performing a checksum
+on the dependency's contents using the selected hash function,
 and comparing it to the checksum recorded the
 last time the target was built.
-<literal>MD5</literal>
-can be used as a synonym for
-<literal>content</literal>, but it is deprecated.
+<literal>content</literal> is the default decider.
+</para>
+<para>
+<emphasis>Changed in version 4.1:</emphasis>
+The decider was renamed to <literal>content</literal>
+since the hash function is now selectable.
+The former name, <literal>MD5</literal>,
+can still be used as a synonym, but is deprecated.
 </para>
 </listitem>
 </varlistentry>
@@ -1339,9 +1334,44 @@ that runs a build,
 updates a file,
 and runs the build again,
 all within a single second.
-<literal>MD5-timestamp</literal>
-can be used as a synonym for
-<literal>content-timestamp</literal>, but it is deprecated.
+</para>
+<para>
+<emphasis>Changed in version 4.1:</emphasis>
+The decider was renamed to <literal>content-timestamp</literal>
+since the hash function is now selectable.
+The former name, <literal>MD5-timestamp</literal>,
+can still be used as a synonym, but is deprecated.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>"timestamp-newer"</literal></term>
+<listitem>
+<para>
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is newer than the target file's timestamp.
+This is the behavior of the classic Make utility,
+and
+<literal>make</literal>
+can be used a synonym for
+<literal>timestamp-newer</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>"timestamp-match"</literal></term>
+<listitem>
+<para>
+Specifies that a target shall be considered out of date and rebuilt
+if the dependency's timestamp is different than the
+timestamp recorded the last time the target was built.
+This provides behavior very similar to the classic Make utility
+(in particular, files are not opened up so that their
+contents can be checksummed)
+except that the target will also be rebuilt if a
+dependency file has been restored to a version with an
+<emphasis>earlier</emphasis>
+timestamp, such as can happen when restoring files from backup archives.
 </para>
 </listitem>
 </varlistentry>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index e79a267d1..b070dcb48 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1216,7 +1216,7 @@ small block-size slows down the build considerably.</para>
 <para>The default value is to use a chunk size of 64 kilobytes, which should
 be appropriate for most uses.</para>
 
-<para><emphasis>New in version 4.2.</emphasis></para>
+<para><emphasis>New in version 4.1.</emphasis></para>
   </listitem>
   </varlistentry>
 
@@ -1256,7 +1256,7 @@ For example, <option>--hash-format=sha256</option> uses a SConsign
 database named <filename>.sconsign_sha256.dblite</filename>.
 </para>
 
-<para><emphasis>New in version 4.2.</emphasis></para>
+<para><emphasis>New in version 4.1.</emphasis></para>
   </listitem>
 </varlistentry>
 
@@ -3961,7 +3961,7 @@ it will not be added again. The default is <literal>False</literal>.
 <parameter>library</parameter> can be a list of library names,
 or <constant>None</constant> (the default if the argument is omitted).
 If the former, <parameter>symbol</parameter> is checked against
-each library name in order, returning 
+each library name in order, returning
 (and reporting success) on the first
 successful test; if the latter,
 it is checked with the current value of &cv-LIBS;
@@ -6526,9 +6526,11 @@ env.Command(
 </programlisting>
 
 <para>
-The behavior of <function>Chmod</function> is limited on Windows,
+The behavior of <function>Chmod</function> is limited on Windows
+and on WebAssembly platforms,
 see the notes in the Python documentation for
-<systemitem>os.chmod</systemitem>, which is the underlying function.
+<ulink url="https://docs.python.org/3/library/os.html#os.chmod">
+os.chmod</ulink>, which is the underlying function.
 </para>
 
   </listitem>
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index 69368d72d..f00bd694f 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -129,7 +129,7 @@ CacheDir('/usr/local/build_cache')
       A few inside details: &SCons; tracks two main kinds of cryptographic
       hashes: a <emphasis>&contentsig;</emphasis>,
       which is a hash of the contents of a file participating in the
-      build (depepdencies as well as targets);
+      build (dependencies as well as targets);
       and a <emphasis>&buildsig;</emphasis>, which is a hash of the
       elements needed to build a target, such as the command line,
       the contents of the sources, and possibly information about