[Emacs-diffs] emacs-25 1f85b7c: Doc fixes re alist-get. (Bug#23548)

[Glenn Morris]

branch: emacs-25
commit 1f85b7ca034ee4f96d796d95ec86bc4fa0ba8aa3
Author: Glenn Morris <address@hidden>
Commit: Glenn Morris <address@hidden>

    Doc fixes re alist-get.  (Bug#23548)
    
    * lisp/subr.el (alist-get): Doc fix.
    * doc/lispref/lists.texi (Association Lists): Improve alist-get.
    ; * etc/NEWS: Related edit.
---
 doc/lispref/lists.texi |   12 ++++++++----
 etc/NEWS               |    3 ++-
 lisp/subr.el           |   10 ++++++----
 3 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c18c408..e7a739f 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,12 +1556,16 @@ keys may not be symbols:
 @end smallexample
 @end defun
 
address@hidden alist-get key value &optional default
address@hidden alist-get key value &optional default remove
 This function is like @code{assq}, but instead of returning the entire
 association for @var{key}, @code{(@var{key} . @var{value})}, it
-returns just the @var{value}.  It returns @var{default} if @var{key}
-is not found in @var{alist}, defaulting to @code{nil} if @var{default}
-is omitted.
+returns just the @var{value}.  If @var{key} is not found in
address@hidden it returns @var{default}.
+
+This is a generalized variable (@pxref{Generalized Variables}) that
+can be used to change a value with @code{setf}.  When using it to set
+a value, optional argument @var{remove} non-nil means to remove
address@hidden from @var{alist} if the new value is @code{eql} to @var{default}.
 @end defun
 
 @defun rassq value alist
diff --git a/etc/NEWS b/etc/NEWS
index 00515f5..56074ce 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1680,7 +1680,8 @@ codeset is "UTF-8" (as in "en_US.UTF-8").  This is needed 
because
 MS-Windows doesn't support UTF-8 as codeset in its locales.
 
 +++
-** New function 'alist-get', which is also a valid place (aka lvalue).
+** New function 'alist-get', which is a generalized variable
+suitable for use with 'setf'.
 
 +++
 ** New function 'funcall-interactively', which works like 'funcall'
diff --git a/lisp/subr.el b/lisp/subr.el
index 81570d4..ed2166a 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -598,10 +598,12 @@ Elements of ALIST that are not conses are ignored."
   alist)
 
 (defun alist-get (key alist &optional default remove)
-  "Get the value associated to KEY in ALIST.
-DEFAULT is the value to return if KEY is not found in ALIST.
-REMOVE, if non-nil, means that when setting this element, we should
-remove the entry if the new value is `eql' to DEFAULT."
+  "Return the value associated with KEY in ALIST, using `assq'.
+If KEY is not found in ALIST, return DEFAULT.
+
+This is a generalized variable suitable for use with `setf'.
+When using it to set a value, optional argument REMOVE non-nil
+means to remove KEY from ALIST if the new value is `eql' to DEFAULT."
   (ignore remove) ;;Silence byte-compiler.
   (let ((x (assq key alist)))
     (if x (cdr x) default)))