Improve documentation of 'copy-sequence'

* src/fns.c (Fcopy_sequence):
* doc/lispref/sequences.texi (Sequence Functions): Mention the
exception when copying an empty sequence.  (Bug#28627)

2 files changed, 7 insertions, 2 deletions

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index c7cf9f5e1af..5ae1567c128 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -155,7 +155,10 @@ This function generalizes @code{aref} (@pxref{Array Functions}) and
 @cindex copying sequences
 This function returns a copy of @var{seqr}, which should be either a
 sequence or a record.  The copy is the same type of object as the
-original, and it has the same elements in the same order.
+original, and it has the same elements in the same order.  However, if
+@var{seqr} is empty, like a string or a vector of zero length, the
+value returned by this function might not be a copy, but an empty
+object of the same type and identical to @var{seqr}.
 
 Storing a new element into the copy does not affect the original
 @var{seqr}, and vice versa.  However, the elements of the copy
diff --git a/src/fns.c b/src/fns.c
index 4524ff9b268..2311a6e041b 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -482,7 +482,9 @@ usage: (vconcat &rest SEQUENCES)   */)
 DEFUN ("copy-sequence", Fcopy_sequence, Scopy_sequence, 1, 1, 0,
        doc: /* Return a copy of a list, vector, string, char-table or record.
 The elements of a list, vector or record are not copied; they are
-shared with the original.  */)
+shared with the original.
+If the original sequence is empty, this function may return
+the same empty object instead of its copy.  */)
   (Lisp_Object arg)
 {
   if (NILP (arg)) return arg;