* lisp/emacs-lisp/map.el: Better docstrings.

1 files changed, 12 insertions, 11 deletions

diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el
index cc437e02e78..5ef51f12d96 100644
--- a/lisp/emacs-lisp/map.el
+++ b/lisp/emacs-lisp/map.el
@@ -45,12 +45,12 @@
 (require 'seq)
 
 (pcase-defmacro map (&rest args)
-  "pcase pattern matching map elements.
+  "Build a `pcase' pattern matching map elements.
 
-Matches if the object is a map (list, hash-table or array), and
-each PATTERN matches the corresponding elements of the map.
+The `pcase' pattern will match each element of PATTERN against
+the corresponding elements of the map.
 
-Supernumerary elements of the map are ignored if fewer ARGS are
+Extra elements of the map are ignored if fewer ARGS are
 given, and the match does not fail.
 
 ARGS can be a list of the form (KEY PAT), in which case KEY in an
@@ -92,7 +92,7 @@ Return RESULT if non-nil or the result of evaluation of the form."
            (t (error "Unsupported map: %s" ,map-var)))))
 
 (defun map-elt (map key &optional default)
-  "Perform a lookup in MAP of KEY and return its associated value.
+  "Lookup KEY in MAP and return its associated value.
 If KEY is not found, return DEFAULT which defaults to nil.
 
 If MAP is a list, `eql' is used to lookup KEY.
@@ -122,7 +122,7 @@ MAP can be a list, hash-table or array."
              default)))
 
 (defmacro map-put (map key value)
-  "In MAP, associate KEY with VALUE and return MAP.
+  "Associate KEY with VALUE in MAP and return MAP.
 If KEY is already present in MAP, replace the associated value
 with VALUE.
 
@@ -133,8 +133,9 @@ MAP can be a list, hash-table or array."
        ,map)))
 
 (defmacro map-delete (map key)
-  "In MAP, delete the key KEY if present and return MAP.
-If MAP is an array, store nil at the index KEY.
+  "Delete KEY from MAP and return MAP.
+No error is signaled if KEY is not a key of MAP.  If MAP is an
+array, store nil at the index KEY.
 
 MAP can be a list, hash-table or array."
   (declare (debug t))
@@ -245,7 +246,7 @@ MAP can be a list, hash-table or array."
       (arrayp map)))
 
 (defun map-empty-p (map)
-  "Return non-nil is MAP is empty.
+  "Return non-nil if MAP is empty.
 
 MAP can be a list, hash-table or array."
   (map--dispatch map
@@ -254,7 +255,7 @@ MAP can be a list, hash-table or array."
     :hash-table (zerop (hash-table-count map))))
 
 (defun map-contains-key (map key &optional testfn)
-  "Return non-nil if MAP contain the key KEY, nil otherwise.
+  "Return non-nil if MAP contain KEY, nil otherwise.
 Equality is defined by TESTFN if non-nil or by `equal' if nil.
 
 MAP can be a list, hash-table or array."
@@ -284,7 +285,7 @@ MAP can be a list, hash-table or array."
     t))
 
 (defun map-merge (type &rest maps)
-  "Merge into a map of type TYPE all the key/value pairs in the maps MAPS.
+  "Merge into a map of type TYPE all the key/value pairs in MAPS.
 
 MAP can be a list, hash-table or array."
   (let (result)