list-builder: inserter methods return nil.

* share/txr/stdlib/build.tl (list-builder): Methods add, add*,
pend, pend*, ncon and ncon* return nil.

* txr.1: Updated documentation to state that these methods
return nil, rather than an unspecified return value.
Improvements in build macro documentation.

2 files changed, 44 insertions, 24 deletions

diff --git a/share/txr/stdlib/build.tl b/share/txr/stdlib/build.tl
index c7af1df7..32df083d 100644
--- a/share/txr/stdlib/build.tl
+++ b/share/txr/stdlib/build.tl
@@ -36,13 +36,15 @@
       (usr:rplacd tl (copy (cdr tl)))
       (set tl (last tl))
       (usr:rplacd tl items)
-      (set self.tail tl)))
+      (set self.tail tl))
+    nil)
 
   (:method add* (self . items)
     (let ((ic (copy items))
           (h self.head))
       (usr:rplacd (last ic) (cdr h))
-      (usr:rplacd h ic)))
+      (usr:rplacd h ic))
+    nil)
 
   (:method pend (self . lists)
     (let ((tl self.tail))
@@ -51,7 +53,8 @@
         (set tl (last tl))
         (usr:rplacd tl (car lists))
         (set lists (cdr lists)))
-      (set self.tail tl)))
+      (set self.tail tl))
+    nil)
 
   (:method pend* (self . lists)
     (let* ((h self.head)
@@ -62,10 +65,10 @@
         (set tl (last tl))
         (usr:rplacd tl (car lists))
         (set lists (cdr lists)))
-
       (set tl (last tl))
       (usr:rplacd tl (cdr h))
-      (set self.head nh)))
+      (set self.head nh))
+    nil)
 
   (:method ncon (self . lists)
     (let ((tl self.tail))
@@ -73,14 +76,16 @@
         (set tl (last tl))
         (usr:rplacd tl (car lists))
         (set lists (cdr lists)))
-      (set self.tail tl)))
+      (set self.tail tl))
+    nil)
 
   (:method ncon* (self . lists)
     (let* ((h self.head)
            (pf (nconc (nconc . lists) (cdr h))))
       (usr:rplacd h pf)
       (if (eq self.tail h)
-        (set self.tail pf))))
+        (set self.tail pf)))
+    nil)
 
   (:method get (self)
     (cdr self.head))
diff --git a/txr.1 b/txr.1
index ad72c762..031d7d9e 100644
--- a/txr.1
+++ b/txr.1
@@ -32181,7 +32181,8 @@ whereas
 .code add*
 adds elements at the front.
 
-The return value of these methods is unspecified.
+These methods return
+.codn nil .
 
 .TP* Example:
 
@@ -32225,7 +32226,8 @@ Both methods have the property that the
 constructed list does not share structure
 with the input lists.
 
-The return value of these methods is unspecified.
+These methods return
+.codn nil .
 
 .TP* Example:
 
@@ -32277,7 +32279,8 @@ which is an atom. This atom will simply be
 installed as the terminating atom of the
 list being constructed.
 
-The return value of these methods is unspecified.
+These methods return
+.codn nil .
 
 .TP* Example:
 
@@ -32374,19 +32377,37 @@ structure. They eliminate the explicit call to the
 function to construct the object, and eliminate the explicit
 references to the object.
 
-Instead,
-.code build
-and
-.code buildn
-creates a lexical environment in which a
+Both of these macros create a lexical environment in which a
 .code list-builder
 object is implicitly constructed and bound to a hidden variable.
-Local functions which mimic the
+This lexical environment also provides local functions named
+.codn add ,
+.codn add* ,
+.codn pend ,
+.codn pend* ,
+.codn ncon ,
+.codn ncon* ,
+.codn get ,
+.code del
+and
+.codn del* ,
+
+which mimic the
 .code list-builder
-methods operate implicitly on this hidden variable, so that
+methods, but operate implicitly on this hidden variable, so that
 the object need not be mentioned as an argument.
+With the exception of
+.codn get ,
+.code del
+and
+.codn del* ,
+the local functions return
+.codn nil ,
+like the same-named
+.code list-builder
+methods.
 
-Then, each
+In this lexical environment, each
 .meta form
 is evaluated in order.
 
@@ -32402,12 +32423,6 @@ returns the value of the last
 If no forms are enclosed, both macros return
 .codn nil .
 
-With the exception of
-.codn get ,
-the local functions have unspecified return values, like the same-named
-.code list-builder
-methods.
-
 Note: because the local function
 .code del
 has the same name as a global macro, it is implemented as a