From 22579baf62fc5e6a4f0482172eb7a4e71d6fbcda Mon Sep 17 00:00:00 2001 From: Nicolas Petton Date: Mon, 26 Oct 2015 22:23:02 +0100 Subject: [PATCH] * lisp/emacs-lisp/map.el: Better docstrings. --- lisp/emacs-lisp/map.el | 23 ++++++++++++----------- 1 file 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) -- 2.39.2