Merge pull request #4648 from mwichmann/doc/clean-noclean

Tweak Clean and NoClean manpage entries

5 files changed, 92 insertions, 128 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 227a56f..8ffb07d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -149,6 +149,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       always returns  a dict. The default remains to return different
       types depending on whether zero, one, or multiple construction
       variable names are given.
+    - Update Clean and NoClean documentation.
 
 
 RELEASE 4.8.1 -  Tue, 03 Sep 2024 17:22:20 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index 72ec73c..77afdef 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -176,6 +176,7 @@ DOCUMENTATION
 
 - Many grammatical and spelling fixes in the documentation.
 
+- Update Clean and NoClean documentation.
 
 DEVELOPMENT
 -----------
diff --git a/SCons/Environment.py b/SCons/Environment.py
index 62926f5..468da23 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -2248,6 +2248,16 @@ class Base(SubstitutionEnvironment):
             self.get_CacheDir()
 
     def Clean(self, targets, files) -> None:
+        """Mark additional files for cleaning.
+
+        *files* will be removed if any of *targets* are selected
+        for cleaning - that is, the combination of target selection
+        and -c clean mode.
+
+        Args:
+            targets (files or nodes): targets to associate *files* with.
+            files (files or nodes): items to remove if *targets* are selected.
+        """
         global CleanTargets
         tlist = self.arg2nodes(targets, self.fs.Entry)
         flist = self.arg2nodes(files, self.fs.Entry)
@@ -2334,8 +2344,8 @@ class Base(SubstitutionEnvironment):
             return result
         return self.fs.PyPackageDir(s)
 
-    def NoClean(self, *targets):
-        """Tag target(s) so that it will not be cleaned by -c."""
+    def NoClean(self, *targets) -> list:
+        """Tag *targets* to not be removed in clean mode."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index dafc649..f24c2af 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -1010,45 +1010,34 @@ to arrange for cache pruning, expiry, access control, etc. if needed.
 
 <scons_function name="Clean">
 <arguments>
-(targets, files_or_dirs)
+(targets, files)
 </arguments>
 <summary>
 <para>
-This specifies a list of files or directories which should be removed
-whenever the targets are specified with the
-<option>-c</option>
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-&f-Clean;
-are legal,
-and create new targets or add files and directories to the
-clean list for the specified targets.
-</para>
-
-<para>
-Multiple files or directories should be specified
-either as separate arguments to the
-&f-Clean;
-method, or as a list.
-&f-Clean;
-will also accept the return value of the &consenv;
-Builder methods.
-Examples:
+Set additional <parameter>files</parameter>
+for removal when any of
+<parameter>targets</parameter> are selected
+for cleaning
+(<link linkend="opt-clean"><option>-c</option></link>
+command line option).
+<parameter>targets</parameter> and
+<parameter>files</parameter>
+can each be a single filename or node,
+or a list of filenames or nodes.
+These can refer to files or directories.
+Calling this method repeatedly
+has an additive effect.
 </para>
 
 <para>
 The related
 &f-link-NoClean;
-function overrides calling
-&f-Clean;
-for the same target,
-and any targets passed to both functions will
-<emphasis>not</emphasis>
-be removed by the
-<option>-c</option>
-option.
+method has higher priority:
+any target specified to
+&f-NoClean;
+will not be cleaned even if also given as
+a <parameter>files</parameter>
+parameter to &f-Clean;.
 </para>
 
 <para>
@@ -1062,9 +1051,12 @@ Clean(['foo', 'bar'], 'something_else_to_clean')
 </example_commands>
 
 <para>
+&SCons; does not directly track directories as targets -
+they are created if needed and not normally removed
+in clean mode.
 In this example,
 installing the project creates a subdirectory for the documentation.
-This statement causes the subdirectory to be removed
+The &f-Clean; call ensures that the subdirectory is removed
 if the project is uninstalled.
 </para>
 <example_commands>
@@ -2525,35 +2517,21 @@ NoCache(env.Program('hello', 'hello.c'))
 
 <scons_function name="NoClean">
 <arguments>
-(target, ...)
+(targets, ...)
 </arguments>
 <summary>
 <para>
-Specifies a list of files or directories which should
-<emphasis>not</emphasis>
-be removed whenever the targets (or their dependencies)
-are specified with the
-<option>-c</option>
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-&f-NoClean;
-are legal,
-and prevent each specified target
-from being removed by calls to the
-<option>-c</option>
-option.
-</para>
-
-<para>
-Multiple files or directories should be specified
-either as separate arguments to the
-&f-NoClean;
-method, or as a list.
-&f-NoClean;
-will also accept the return value of any of the &consenv;
-Builder methods.
+Specifies files or directories which should not
+be removed whenever a specified
+<parameter>target</parameter> (or its dependencies)
+is selected and clean mode is active
+(<link linkend="opt-clean"><option>-c</option></link>
+command line option).
+<parameter>targets</parameter>
+may be one or more file or directory names
+or nodes,
+and/or lists of names or nodes.
+&f-NoClean; can be called multiple times.
 </para>
 
 <para>
@@ -2562,11 +2540,9 @@ Calling
 for a target overrides calling
 &f-link-Clean;
 for the same target,
-and any targets passed to both functions will
+so any targets passed to both functions will
 <emphasis>not</emphasis>
-be removed by the
-<option>-c</option>
-option.
+be removed in clean mode.
 </para>
 
 <para>
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index 9668af8..b5fcfcc 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -927,44 +927,33 @@ to arrange for cache pruning, expiry, access control, etc. if needed.
 </listitem>
   </varlistentry>
   <varlistentry id="f-Clean">
-    <term><function>Clean</function>(<parameter>targets, files_or_dirs</parameter>)</term>
-    <term><replaceable>env</replaceable>.<methodname>Clean</methodname>(<parameter>targets, files_or_dirs</parameter>)</term>
+    <term><function>Clean</function>(<parameter>targets, files</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>Clean</methodname>(<parameter>targets, files</parameter>)</term>
     <listitem><para>
-This specifies a list of files or directories which should be removed
-whenever the targets are specified with the
-<option>-c</option>
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-&f-Clean;
-are legal,
-and create new targets or add files and directories to the
-clean list for the specified targets.
-</para>
-
-<para>
-Multiple files or directories should be specified
-either as separate arguments to the
-&f-Clean;
-method, or as a list.
-&f-Clean;
-will also accept the return value of the &consenv;
-Builder methods.
-Examples:
+Set additional <parameter>files</parameter>
+for removal when any of
+<parameter>targets</parameter> are selected
+for cleaning
+(<link linkend="opt-clean"><option>-c</option></link>
+command line option).
+<parameter>targets</parameter> and
+<parameter>files</parameter>
+can each be a single filename or node,
+or a list of filenames or nodes.
+These can refer to files or directories.
+Calling this method repeatedly
+has an additive effect.
 </para>
 
 <para>
 The related
 &f-link-NoClean;
-function overrides calling
-&f-Clean;
-for the same target,
-and any targets passed to both functions will
-<emphasis>not</emphasis>
-be removed by the
-<option>-c</option>
-option.
+method has higher priority:
+any target specified to
+&f-NoClean;
+will not be cleaned even if also given as
+a <parameter>files</parameter>
+parameter to &f-Clean;.
 </para>
 
 <para>
@@ -978,9 +967,12 @@ Clean(['foo', 'bar'], 'something_else_to_clean')
 </example_commands>
 
 <para>
+&SCons; does not directly track directories as targets -
+they are created if needed and not normally removed
+in clean mode.
 In this example,
 installing the project creates a subdirectory for the documentation.
-This statement causes the subdirectory to be removed
+The &f-Clean; call ensures that the subdirectory is removed
 if the project is uninstalled.
 </para>
 <example_commands>
@@ -3056,34 +3048,20 @@ NoCache(env.Program('hello', 'hello.c'))
 </listitem>
   </varlistentry>
   <varlistentry id="f-NoClean">
-    <term><function>NoClean</function>(<parameter>target, ...</parameter>)</term>
-    <term><replaceable>env</replaceable>.<methodname>NoClean</methodname>(<parameter>target, ...</parameter>)</term>
+    <term><function>NoClean</function>(<parameter>targets, ...</parameter>)</term>
+    <term><replaceable>env</replaceable>.<methodname>NoClean</methodname>(<parameter>targets, ...</parameter>)</term>
     <listitem><para>
-Specifies a list of files or directories which should
-<emphasis>not</emphasis>
-be removed whenever the targets (or their dependencies)
-are specified with the
-<option>-c</option>
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-&f-NoClean;
-are legal,
-and prevent each specified target
-from being removed by calls to the
-<option>-c</option>
-option.
-</para>
-
-<para>
-Multiple files or directories should be specified
-either as separate arguments to the
-&f-NoClean;
-method, or as a list.
-&f-NoClean;
-will also accept the return value of any of the &consenv;
-Builder methods.
+Specifies files or directories which should not
+be removed whenever a specified
+<parameter>target</parameter> (or its dependencies)
+is selected and clean mode is active
+(<link linkend="opt-clean"><option>-c</option></link>
+command line option).
+<parameter>targets</parameter>
+may be one or more file or directory names
+or nodes,
+and/or lists of names or nodes.
+&f-NoClean; can be called multiple times.
 </para>
 
 <para>
@@ -3092,11 +3070,9 @@ Calling
 for a target overrides calling
 &f-link-Clean;
 for the same target,
-and any targets passed to both functions will
+so any targets passed to both functions will
 <emphasis>not</emphasis>
-be removed by the
-<option>-c</option>
-option.
+be removed in clean mode.
 </para>
 
 <para>