[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-27 5805df7 3/3: Improve mutability doc
From: |
Paul Eggert |
Subject: |
emacs-27 5805df7 3/3: Improve mutability doc |
Date: |
Sun, 19 Apr 2020 16:30:03 -0400 (EDT) |
branch: emacs-27
commit 5805df74f5b919a3f67f3f7d31d6e600e1564e4e
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>
Improve mutability doc
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 f1acc85..1125af7 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 62d6015..1cb0d05 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 ?-)