Improve the docstring of functions in map.el

Since a map is not a data structure but a concept, adding information
about the possible types of maps can be useful information.

* lisp/emacs-lisp/map.el: Add documentation about the type of MAP to
each public function.

1 files changed, 58 insertions, 19 deletions

diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el
index 18d2963f46c..8801b2aba7a 100644
--- a/lisp/emacs-lisp/map.el
+++ b/lisp/emacs-lisp/map.el
@@ -48,7 +48,9 @@
   "Perform a lookup in MAP of KEY and return its associated value.
 If KEY is not found, return DEFAULT which defaults to nil.
 
-If MAP is a list, `equal' is used to lookup KEY."
+If MAP is a list, `equal' is used to lookup KEY.
+
+MAP can be a list, hash-table or array."
   (map--dispatch map
     :list (map--elt-list map key default)
     :hash-table (gethash key map default)
@@ -57,7 +59,9 @@ If MAP is a list, `equal' is used to lookup KEY."
 (defmacro map-put (map key value)
   "In MAP, associate KEY with VALUE and return MAP.
 If KEY is already present in MAP, replace the associated value
-with VALUE."
+with VALUE.
+
+MAP can be a list, hash-table or array."
   (declare (debug t))
   `(progn
      (map--dispatch (m ,map m)
@@ -67,7 +71,9 @@ with VALUE."
 
 (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."
+If MAP is an array, store nil at the index KEY.
+
+MAP can be a list, hash-table or array."
   (declare (debug t))
   `(progn
      (map--dispatch (m ,map m)
@@ -77,6 +83,7 @@ If MAP is an array, store nil at the index KEY."
 
 (defun map-nested-elt (map keys &optional default)
   "Traverse MAP using KEYS and return the looked up value or DEFAULT if nil.
+
 Map can be a nested map composed of alists, hash-tables and arrays."
   (or (seq-reduce (lambda (acc key)
                     (when (map-p acc)
@@ -86,23 +93,33 @@ Map can be a nested map composed of alists, hash-tables and arrays."
       default))
 
 (defun map-keys (map)
-  "Return the list of keys in MAP."
+  "Return the list of keys in MAP.
+
+MAP can be a list, hash-table or array."
   (map-apply (lambda (key _) key) map))
 
 (defun map-values (map)
-  "Return the list of values in MAP."
+  "Return the list of values in MAP.
+
+MAP can be a list, hash-table or array."
   (map-apply (lambda (_ value) value) map))
 
 (defun map-pairs (map)
-  "Return the elements of MAP as key/value association lists."
+  "Return the elements of MAP as key/value association lists.
+
+MAP can be a list, hash-table or array."
   (map-apply #'cons map))
 
 (defun map-length (map)
-  "Return the length of MAP."
+  "Return the length of MAP.
+
+MAP can be a list, hash-table or array."
   (length (map-keys map)))
 
 (defun map-copy (map)
-  "Return a copy of MAP."
+  "Return a copy of MAP.
+
+MAP can be a list, hash-table or array."
   (map--dispatch map
     :list (seq-copy map)
     :hash-table (copy-hash-table map)
@@ -110,7 +127,9 @@ Map can be a nested map composed of alists, hash-tables and arrays."
 
 (defun map-apply (function map)
   "Apply FUNCTION to each element of MAP and return the result as a list.
-FUNCTION is called with two arguments, the key and the value."
+FUNCTION is called with two arguments, the key and the value.
+
+MAP can be a list, hash-table or array."
   (funcall (map--dispatch map
              :list #'map--apply-alist
              :hash-table #'map--apply-hash-table
@@ -119,19 +138,25 @@ FUNCTION is called with two arguments, the key and the value."
            map))
 
 (defun map-keys-apply (function map)
-  "Return the result of applying FUNCTION to each key of MAP."
+  "Return the result of applying FUNCTION to each key of MAP.
+
+MAP can be a list, hash-table or array."
   (map-apply (lambda (key _)
                (funcall function key))
              map))
 
 (defun map-values-apply (function map)
-  "Return the result of applying FUNCTION to each value of MAP."
+  "Return the result of applying FUNCTION to each value of MAP.
+
+MAP can be a list, hash-table or array."
   (map-apply (lambda (_ val)
                (funcall function val))
              map))
 
 (defun map-filter (pred map)
-  "Return an alist of the key/val pairs for which (PRED key val) is non-nil in MAP."
+  "Return an alist of the key/val pairs for which (PRED key val) is non-nil in MAP.
+
+MAP can be a list, hash-table or array."
   (delq nil (map-apply (lambda (key val)
                          (if (funcall pred key val)
                              (cons key val)
@@ -139,7 +164,9 @@ FUNCTION is called with two arguments, the key and the value."
                        map)))
 
 (defun map-remove (pred map)
-  "Return an alist of the key/val pairs for which (PRED key val) is nil in MAP."
+  "Return an alist of the key/val pairs for which (PRED key val) is nil in MAP.
+
+MAP can be a list, hash-table or array."
   (map-filter (lambda (key val) (not (funcall pred key val)))
               map))
 
@@ -150,7 +177,9 @@ FUNCTION is called with two arguments, the key and the value."
       (arrayp map)))
 
 (defun map-empty-p (map)
-  "Return non-nil is MAP is empty."
+  "Return non-nil is MAP is empty.
+
+MAP can be a list, hash-table or array."
   (map--dispatch map
     :list (null map)
     :array (seq-empty-p map)
@@ -158,11 +187,15 @@ FUNCTION is called with two arguments, the key and the value."
 
 (defun map-contains-key-p (map key &optional testfn)
   "Return non-nil if MAP contain the key KEY, nil otherwise.
-Equality is defined by TESTFN if non-nil or by `equal' if nil."
+Equality is defined by TESTFN if non-nil or by `equal' if nil.
+
+MAP can be a list, hash-table or array."
   (seq-contains-p (map-keys map) key testfn))
 
 (defun map-some-p (pred map)
-  "Return a key/value pair for which (PRED key val) is non-nil in MAP."
+  "Return a key/value pair for which (PRED key val) is non-nil in MAP.
+
+MAP can be a list, hash-table or array."
   (catch 'map--break
     (map-apply (lambda (key value)
                  (when (funcall pred key value)
@@ -171,7 +204,9 @@ Equality is defined by TESTFN if non-nil or by `equal' if nil."
     nil))
 
 (defun map-every-p (pred map)
-  "Return non-nil if (PRED key val) is non-nil for all elements of the map MAP."
+  "Return non-nil if (PRED key val) is non-nil for all elements of the map MAP.
+
+MAP can be a list, hash-table or array."
   (catch 'map--break
     (map-apply (lambda (key value)
                  (or (funcall pred key value)
@@ -180,7 +215,9 @@ Equality is defined by TESTFN if non-nil or by `equal' if nil."
     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 the maps MAPS.
+
+MAP can be a list, hash-table or array."
   (let (result)
     (while maps
       (map-apply (lambda (key value)
@@ -190,7 +227,9 @@ Equality is defined by TESTFN if non-nil or by `equal' if nil."
 
 (defun map-into (map type)
   "Convert the map MAP into a map of type TYPE.
-TYPE can be one of the following symbols: list or hash-table."
+
+TYPE can be one of the following symbols: list or hash-table.
+MAP can be a list, hash-table or array."
   (pcase type
     (`list (map-pairs map))
     (`hash-table (map--into-hash-table map))