[Emacs-diffs] master a5995a3 2/4: Improve flatten-tree documentation

[Paul Eggert]

branch: master
commit a5995a326d1dad9bccf1ad7eb96e4e8146f6dcbe
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    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.
---
 doc/lispref/lists.texi | 10 +++++-----
 lisp/subr.el           | 14 +++++---------
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 31cc319..0a1d5b5 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 address@hidden 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 3dec6cf..c5004a5 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)))