Improve flatten-tree documentation

* doc/lispref/lists.texi (Building Lists):
* lisp/subr.el (flatten-tree):
Don’t imply that flatten-tree modifies its argument.
Clarify wording.

2 files changed, 10 insertions, 14 deletions

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 31cc3190854..0a1d5b5dc33 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -668,10 +668,10 @@ their elements).
 @end defun
 
 @defun flatten-tree tree
-Take @var{tree} and "flatten" it.
-This always returns a list containing all the terminal nodes, or
-leaves, of @var{tree}.  Dotted pairs are flattened as well, and nil
-elements are removed.
+This function returns a ``flattened'' copy of @var{tree}, that is,
+a list containing all the non-@code{nil} terminal nodes, or leaves, of
+the tree of cons cells rooted at @var{tree}.  Leaves in the returned
+list are in the same order as in @var{tree}.
 @end defun
 
 @example
@@ -680,7 +680,7 @@ elements are removed.
 @end example
 
 @defun number-sequence from &optional to separation
-This returns a list of numbers starting with @var{from} and
+This function returns a list of numbers starting with @var{from} and
 incrementing by @var{separation}, and ending at or just before
 @var{to}.  @var{separation} can be positive or negative and defaults
 to 1.  If @var{to} is @code{nil} or numerically equal to @var{from},
diff --git a/lisp/subr.el b/lisp/subr.el
index 3dec6cf66c3..c5004a539b0 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -5449,17 +5449,13 @@ This function is called from lisp/Makefile and leim/Makefile."
   file)
 
 (defun flatten-tree (tree)
-  "Take TREE and \"flatten\" it.
-This always returns a list containing all the terminal nodes, or
-\"leaves\", of TREE.  Dotted pairs are flattened as well, and nil
-elements are removed.
+  "Return a \"flattened\" copy of TREE.
+In other words, return a list of the non-nil terminal nodes, or
+leaves, of the tree of cons cells rooted at TREE.  Leaves in the
+returned list are in the same order as in TREE.
 
 \(flatten-tree \\='(1 (2 . 3) nil (4 5 (6)) 7))
-=> (1 2 3 4 5 6 7)
-
-TREE can be anything that can be made into a list.  For each
-element in TREE, if it is a cons cell return its car
-recursively.  Otherwise return the element."
+=> (1 2 3 4 5 6 7)"
   (let (elems)
     (while (consp tree)
       (let ((elem (pop tree)))