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

* 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 version marking.
* Minor fiddling with Alias.py docstrings.

Signed-off-by: Mats Wichmann <mats@linux.com>

2 files changed, 115 insertions, 82 deletions

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>