master 9de0b06e74 3/3: Clarify `take` and `ntake` documentation (bug#56521)

[Mattias Engdegård]

branch: master
commit 9de0b06e7470cc047c96c59befe40077dc72b98d
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Clarify `take` and `ntake` documentation (bug#56521)
    
    * doc/lispref/lists.texi (List Elements): Describe `ntake` better.
    * src/fns.c (Ftake, Fntake): Rephrase doc strings.
---
 doc/lispref/lists.texi | 13 +++++++++++--
 src/fns.c              |  5 +++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 2a9ad1d5e0..bfdba89784 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -344,7 +344,7 @@ If @var{n} is zero, @code{nthcdr} returns all of
 This function returns the @var{n} first elements of @var{list}.  Essentially,
 it returns the part of @var{list} that @code{nthcdr} skips.
 
-@code{take} returns @var{list} if it is shorter than @var{n} elements;
+@code{take} returns @var{list} if shorter than @var{n} elements;
 it returns @code{nil} if @var{n} is zero or negative.
 
 @example
@@ -366,7 +366,16 @@ it returns @code{nil} if @var{n} is zero or negative.
 @defun ntake n list
 This is a version of @code{take} that works by destructively modifying
 the list structure of the argument.  That makes it faster, but the
-original value of @var{list} is lost.
+original value of @var{list} may be lost.
+
+@code{ntake} returns @var{list} unmodified if shorter than @var{n}
+elements; it returns @code{nil} if @var{n} is zero or negative.
+Otherwise, @var{list} is returned after being truncated to its first
+@var{n} elements.
+
+This means that it is usually a good idea to use the return value and
+not just rely on the truncation effect unless @var{n} is known to be
+positive.
 @end defun
 
 @defun last list &optional n
diff --git a/src/fns.c b/src/fns.c
index 84cfec6c3f..7e78bba3a0 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -1560,7 +1560,7 @@ substring_both (Lisp_Object string, ptrdiff_t from, 
ptrdiff_t from_byte,
 DEFUN ("take", Ftake, Stake, 2, 2, 0,
        doc: /* Return the first N elements of LIST.
 If N is zero or negative, return nil.
-If LIST is no more than N elements long, return it (or a copy).  */)
+If N is greater or equal to the length of LIST, return LIST (or a copy).  */)
   (Lisp_Object n, Lisp_Object list)
 {
   CHECK_FIXNUM (n);
@@ -1590,7 +1590,8 @@ If LIST is no more than N elements long, return it (or a 
copy).  */)
 DEFUN ("ntake", Fntake, Sntake, 2, 2, 0,
        doc: /* Modify LIST to keep only the first N elements.
 If N is zero or negative, return nil.
-If LIST is no more than N elements long, return it.  */)
+If N is greater or equal to the length of LIST, return LIST unmodified.
+Otherwise, return LIST after truncating it.  */)
   (Lisp_Object n, Lisp_Object list)
 {
   CHECK_FIXNUM (n);