Merge pull request #4477 from mwichmann/doc/Pseudo-and-neighbors

doc: update Pseudo description and more

6 files changed, 41 insertions, 22 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 357cb45..30543e5 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -80,6 +80,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       Fixes #4468.
     - Fix bad typing in Action.py: process() and strfunction().
     - Add Pseudo() to global functions, had been omitted. Fixes #4474.
+      The Pseudo manpage entry was updated to provide more clarity.
 
 
 RELEASE 4.6.0 -  Sun, 19 Nov 2023 17:22:20 -0700
diff --git a/RELEASE.txt b/RELEASE.txt
index ae43db1..8afc3d9 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -80,6 +80,7 @@ DOCUMENTATION
 - Fixed the Scanner examples in the User Guide to be runnable and added
   some more explantion. Clarified discussion of the scanner function in
   the Scanner Objects section of the manpage.
+- The manpage entry for Pseudo was clarified.
 
 DEVELOPMENT
 -----------
diff --git a/SCons/Environment.py b/SCons/Environment.py
index 64d38b0..e61ec1f 100644
--- a/SCons/Environment.py
+++ b/SCons/Environment.py
@@ -2339,6 +2339,7 @@ class Base(SubstitutionEnvironment):
         return ret
 
     def Precious(self, *targets):
+        """Mark *targets* as precious: do not delete before building."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))
@@ -2347,6 +2348,7 @@ class Base(SubstitutionEnvironment):
         return tlist
 
     def Pseudo(self, *targets):
+        """Mark *targets* as pseudo: must not exist."""
         tlist = []
         for t in targets:
             tlist.extend(self.arg2nodes(t, self.fs.Entry))
@@ -2355,13 +2357,17 @@ class Base(SubstitutionEnvironment):
         return tlist
 
     def Repository(self, *dirs, **kw) -> None:
+        """Specify Repository directories to search."""
         dirs = self.arg2nodes(list(dirs), self.fs.Dir)
         self.fs.Repository(*dirs, **kw)
 
     def Requires(self, target, prerequisite):
-        """Specify that 'prerequisite' must be built before 'target',
-        (but 'target' does not actually depend on 'prerequisite'
-        and need not be rebuilt if it changes)."""
+        """Specify that *prerequisite* must be built before *target*.
+
+        Creates an order-only relationship, not a full dependency.
+        *prerequisite* must exist before *target* can be built, but
+        a change to *prerequisite* does not trigger a rebuild of *target*.
+        """
         tlist = self.arg2nodes(target, self.fs.Entry)
         plist = self.arg2nodes(prerequisite, self.fs.Entry)
         for t in tlist:
diff --git a/SCons/Environment.xml b/SCons/Environment.xml
index 89d9b49..94dab08 100644
--- a/SCons/Environment.xml
+++ b/SCons/Environment.xml
@@ -2988,6 +2988,10 @@ but the target file(s) do not actually
 depend on the prerequisites
 and will not be rebuilt simply because
 the prerequisite file(s) change.
+<parameter>target</parameter> and
+<parameter>prerequisite</parameter> may each
+be a string or Node, or a list of strings or Nodes.
+Returns a list of the affected target nodes.
 </para>
 
 <para>
diff --git a/SCons/Node/__init__.py b/SCons/Node/__init__.py
index 3da4faf..c3a671c 100644
--- a/SCons/Node/__init__.py
+++ b/SCons/Node/__init__.py
@@ -1230,7 +1230,7 @@ class Node(metaclass=NoSlotsPyPy):
         self.precious = precious
 
     def set_pseudo(self, pseudo: bool = True) -> None:
-        """Set the Node's precious value."""
+        """Set the Node's pseudo value."""
         self.pseudo = pseudo
 
     def set_noclean(self, noclean: int = 1) -> None:
@@ -1250,7 +1250,7 @@ class Node(metaclass=NoSlotsPyPy):
         self.always_build = always_build
 
     def exists(self) -> bool:
-        """Does this node exists?"""
+        """Reports whether node exists."""
         return _exists_map[self._func_exists](self)
 
     def rexists(self):
diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml
index 9248668..36e7d30 100644
--- a/SCons/Script/Main.xml
+++ b/SCons/Script/Main.xml
@@ -725,13 +725,12 @@ Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
 </arguments>
 <summary>
 <para>
-Marks each given
-<varname>target</varname>
-as precious so it is not deleted before it is rebuilt. Normally
-&scons;
-deletes a target before building it.
-Multiple targets can be passed in to a single call to
-&f-Precious;.
+Marks <varname>target</varname> as precious so it is not
+deleted before it is rebuilt.
+Normally &SCons; deletes a target before building it.
+Multiple targets can be passed in a single call,
+and may be strings and/or nodes.
+Returns a list of the affected target nodes.
 </para>
 </summary>
 </scons_function>
@@ -742,16 +741,24 @@ Multiple targets can be passed in to a single call to
 </arguments>
 <summary>
 <para>
-This indicates that each given
-<varname>target</varname>
-should not be created by the build rule, and if the target is created,
-an error will be generated. This is similar to the gnu make .PHONY
-target. However, in the vast majority of cases, an
-&f-Alias;
-is more appropriate.
-
-Multiple targets can be passed in to a single call to
-&f-Pseudo;.
+Marks <parameter>target</parameter> as a pseudo target,
+not representing the production of any physical target file.
+If any pseudo <parameter>target</parameter> does exist,
+&SCons; will abort the build with an error.
+Multiple targets can be passed in a single call,
+and may be strings and/or Nodes.
+Returns a list of the affected target nodes.
+</para>
+
+<para>
+&f-Pseudo; may be useful in conjuction with a builder
+call (such as &f-link-Command;) which does not create a physical target,
+and the behavior if the target accidentally existed would be incorrect.
+This is similar in concept to the GNU <application>make</application>
+<literal>.PHONY</literal> target.
+&SCons; also provides a powerful target alias capability
+(see &f-link-Alias;) which may provide more flexibility
+in many situations when defining target names that are not directly built.
 </para>
 </summary>
 </scons_function>