Better document obsolescence of 'values'

* doc/lispref/eval.texi (Eval): Mention that 'values' is obsolete.
* etc/NEWS: Add a rationale for obsoleting 'values'.

2 files changed, 12 insertions, 4 deletions

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 7893895eee9..e1998842cf0 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -862,8 +862,13 @@ expressions that were read, evaluated, and printed from buffers
 (including the minibuffer) by the standard Emacs commands which do
 this.  (Note that this does @emph{not} include evaluation in
 @file{*ielm*} buffers, nor evaluation using @kbd{C-j}, @kbd{C-x C-e},
-and similar evaluation commands in @code{lisp-interaction-mode}.)  The
-elements are ordered most recent first.
+and similar evaluation commands in @code{lisp-interaction-mode}.)
+
+This variable is obsolete, and will be removed in a future version,
+since it constantly enlarges the memory footprint of the Emacs
+process.  For that reason, we recommend against using it.
+
+The elements of @code{values} are ordered most recent first.
 
 @example
 @group
@@ -880,8 +885,8 @@ values
 @end group
 @end example
 
-This variable is useful for referring back to values of forms recently
-evaluated.  It is generally a bad idea to print the value of
+This variable could be useful for referring back to values of forms
+recently evaluated.  It is generally a bad idea to print the value of
 @code{values} itself, since this may be very long.  Instead, examine
 particular elements, like this:
 
diff --git a/etc/NEWS b/etc/NEWS
index 2adcc6f4a7b..3fa22fbb579 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3374,7 +3374,10 @@ back in Emacs 23.1.  The affected functions are: 'make-obsolete',
 
 ** The variable 'keyboard-type' is obsolete and not dynamically scoped any more.
 
++++
 ** The 'values' variable is now obsolete.
+Using it just contributes to the growth of the Emacs memory
+footprint.
 
 +++
 ** The '&define' keyword in an Edebug specification now disables backtracking.