From 5805df74f5b919a3f67f3f7d31d6e600e1564e4e Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sun, 19 Apr 2020 13:22:10 -0700
Subject: [PATCH] Improve mutability doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

See Eli Zaretskii’s suggestions (Bug#40671#33).
* doc/lispref/lists.texi (Setcar, Setcdr, Rearrangement):
* doc/lispref/sequences.texi (Sequence Functions)
(Array Functions):
Add commentary to examples.
* doc/lispref/lists.texi (Sets And Lists):
Revert change to delq example.
---
 doc/lispref/lists.texi     | 16 +++++++---------
 doc/lispref/sequences.texi | 14 ++++++++------
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index f1acc85616..1125af7bec 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -911,7 +911,7 @@ value @var{object}.  For example:
 
 @example
 @group
-(setq x (list 1 2))
+(setq x (list 1 2))  ; @r{Create a mutable list.}
      @result{} (1 2)
 @end group
 @group
@@ -931,7 +931,7 @@ these lists.  Here is an example:
 
 @example
 @group
-;; @r{Create two lists that are partly shared.}
+;; @r{Create two mutable lists that are partly shared.}
 (setq x1 (list 'a 'b 'c))
      @result{} (a b c)
 (setq x2 (cons 'z (cdr x1)))
@@ -1022,11 +1022,11 @@ reached via the @sc{cdr}.
 
 @example
 @group
-(setq x (list 1 2 3))
+(setq x (list 1 2 3))  ; @r{Create a mutable list.}
      @result{} (1 2 3)
 @end group
 @group
-(setcdr x '(4))
+(setcdr x '(4))  ; @r{Modify the list's tail to be a constant list.}
      @result{} (4)
 @end group
 @group
@@ -1135,11 +1135,11 @@ Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
 
 @example
 @group
-(setq x (list 1 2 3))
+(setq x (list 1 2 3))  ; @r{Create a mutable list.}
      @result{} (1 2 3)
 @end group
 @group
-(nconc x '(4 5))
+(nconc x '(4 5))  ; @r{Modify the list's tail to be a constant list.}
      @result{} (1 2 3 4 5)
 @end group
 @group
@@ -1267,9 +1267,7 @@ after those elements.  For example:
 
 @example
 @group
-(equal
- (delq 'a (list 'a 'b 'c))
- (cdr (list 'a 'b 'c)))
+(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
 @end group
 @end example
 
diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 62d60156fb..1cb0d05cc7 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -183,11 +183,11 @@ for other ways to copy sequences.
 
 @example
 @group
-(setq bar (list 1 2))
+(setq bar (list 1 2))  ; @r{Create a mutable list.}
      @result{} (1 2)
 @end group
 @group
-(setq x (vector 'foo bar))
+(setq x (vector 'foo bar))  ; @r{Create a mutable vector.}
      @result{} [foo (1 2)]
 @end group
 @group
@@ -278,7 +278,7 @@ Unlike @code{reverse} the original @var{sequence} may be modified.
 
 @example
 @group
-(setq x (list 'a 'b 'c))
+(setq x (list 'a 'b 'c))  ; @r{Create a mutable list.}
      @result{} (a b c)
 @end group
 @group
@@ -320,7 +320,7 @@ presented graphically:
   For the vector, it is even simpler because you don't need setq:
 
 @example
-(setq x (copy-sequence [1 2 3 4]))
+(setq x (copy-sequence [1 2 3 4]))  ; @r{Create a mutable vector.}
      @result{} [1 2 3 4]
 (nreverse x)
      @result{} [4 3 2 1]
@@ -374,7 +374,7 @@ appears in a different position in the list due to the change of
 
 @example
 @group
-(setq nums (list 1 3 2 6 5 4 0))
+(setq nums (list 1 3 2 6 5 4 0))  ; @r{Create a mutable list.}
      @result{} (1 3 2 6 5 4 0)
 @end group
 @group
@@ -1228,7 +1228,7 @@ This function sets the @var{index}th element of @var{array} to be
 
 @example
 @group
-(setq w (vector 'foo 'bar 'baz))
+(setq w (vector 'foo 'bar 'baz))  ; @r{Create a mutable vector.}
      @result{} [foo bar baz]
 (aset w 0 'fu)
      @result{} fu
@@ -1262,6 +1262,7 @@ each element of @var{array} is @var{object}.  It returns @var{array}.
 
 @example
 @group
+;; @r{Create a mutable vector and then fill it with zeros.}
 (setq a (copy-sequence [a b c d e f g]))
      @result{} [a b c d e f g]
 (fillarray a 0)
@@ -1270,6 +1271,7 @@ a
      @result{} [0 0 0 0 0 0 0]
 @end group
 @group
+;; @r{Create a mutable string and then fill it with "-".}
 (setq s (copy-sequence "When in the course"))
      @result{} "When in the course"
 (fillarray s ?-)
-- 
2.17.1