Merge from origin/emacs-30

67903f5909d Restore the old behavior of `bookmark-write-file'
062da7003f9 ; Improve prompts and error messages in 'info-look'
52dc01f1c8b ; * admin/admin.el (set-version): Note about Android.
fb282da2a07 Avoid double spaces around abbrevations in Texinfo
bc1ab8ac3d8 ; * doc/emacs/custom.texi (Init Rebinding): Fix spacing.
b41ef43af19 ; Fix previous change
5638b1d6bd4 Ispell: Use "personal dictionary" terminology consistently
cc791e7499f ; Check man pages for mistakes less frequently
4ed4792e3b9 ; * admin/release-process: Minor copy-edits.
4a867c823b7 Add language server "ruff server" for Python
9e687c2871f Fix go-ts-mode type declaration indentation (Bug#75785)
f751b3afa4f ; Minor improvements for doc strings in map.el
cda78edc7d9 ; Fix typos
ce50a1d3c18 ; * src/w32.c (w32_memory_info): Fix coding style of last...
58d3d4820ad Fix bug in w32_memory_info
77386412050 Avoid crashes in redisplay due to problematic font setups
0e3687e6006 Improve 'key-valid-p' docstring
9878092d2b9 Minor copyedits in internals.texi
4726900fdc5 Better document side-effect free and pure C functions
04c475a39f2 ; Fix documentation about faces of tool-tip text

# Conflicts:
#	admin/codespell/codespell.exclude

1 files changed, 12 insertions, 10 deletions

diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el
index 9c19dfdda78..72ff5e2221d 100644
--- a/lisp/emacs-lisp/map.el
+++ b/lisp/emacs-lisp/map.el
@@ -71,7 +71,7 @@ to match if any element of ARGS fails to match."
         ,@(map--make-pcase-bindings args)))
 
 (defmacro map-let (keys map &rest body)
-  "Bind the variables in KEYS to the elements of MAP then evaluate BODY.
+  "Bind the variables in KEYS to the elements of MAP, then evaluate BODY.
 
 KEYS can be a list of symbols, in which case each element will be
 bound to the looked up value in MAP.
@@ -192,7 +192,7 @@ or array."
   "Associate KEY with VALUE in MAP and return VALUE.
 If KEY is already present in MAP, replace the associated value
 with VALUE.
-When MAP is an alist, test equality with TESTFN if non-nil,
+If MAP is an alist, test equality with TESTFN if non-nil,
 otherwise use `equal'.
 
 MAP can be an alist, plist, hash-table, or array."
@@ -318,7 +318,7 @@ The default implementation delegates to `map-do'."
 
 (cl-defgeneric 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 of an element and its value.
 The default implementation delegates to `map-do'."
   (let ((res '()))
     (map-do (lambda (k v) (push (funcall function k v) res)) map)
@@ -339,7 +339,7 @@ The default implementation delegates to `map-apply'."
              map))
 
 (cl-defgeneric map-values-apply (function map)
-  "Return the result of applying FUNCTION to each value in MAP.
+  "Return the result of applying FUNCTION to the value of each key in MAP.
 The default implementation delegates to `map-apply'."
   (map-apply (lambda (_ val)
                (funcall function val))
@@ -407,8 +407,9 @@ If MAP is a plist, TESTFN defaults to `eq'."
     (not (eq v (gethash key map v)))))
 
 (cl-defgeneric map-some (pred map)
-  "Return the first non-nil (PRED key val) in MAP.
+  "Return the first non-nil value from applying PRED to elements of MAP.
 Return nil if no such element is found.
+PRED is called with two arguments: the key of an element and its value.
 The default implementation delegates to `map-do'."
   ;; FIXME: Not sure if there's much benefit to defining it as defgeneric,
   ;; since as defined, I can't think of a map-type where we could provide an
@@ -422,7 +423,8 @@ The default implementation delegates to `map-do'."
     nil))
 
 (cl-defgeneric map-every-p (pred map)
-  "Return non-nil if (PRED key val) is non-nil for all elements of MAP.
+  "Return non-nil if calling PRED on all elements of MAP returns non-nil.
+PRED is called with two arguments: the key of an element and its value.
 The default implementation delegates to `map-do'."
   ;; FIXME: Not sure if there's much benefit to defining it as defgeneric,
   ;; since as defined, I can't think of a map-type where we could provide an
@@ -436,7 +438,7 @@ The default implementation delegates to `map-do'."
 
 (defun map--merge (merge type &rest maps)
   "Merge into a map of TYPE all the key/value pairs in MAPS.
-MERGE is a function that takes the target MAP, a KEY, and a
+MERGE is a function that takes the target MAP, a KEY and its
 VALUE, merges KEY and VALUE into MAP, and returns the result.
 MAP may be of a type other than TYPE."
   ;; Use a hash table internally if `type' is a list.  This avoids
@@ -466,7 +468,7 @@ See `map-into' for all supported values of TYPE."
 (defun map-merge-with (type function &rest maps)
   "Merge into a map of TYPE all the key/value pairs in MAPS.
 When two maps contain the same key, call FUNCTION on the two
-values and use the value returned by it.
+values and use the value FUNCTION returns.
 Each of MAPS can be an alist, plist, hash-table, or array.
 See `map-into' for all supported values of TYPE."
   (let ((not-found (list nil)))
@@ -502,8 +504,8 @@ See `map-into' for all supported values of TYPE."
   "Associate KEY with VALUE in MAP.
 If KEY is already present in MAP, replace the associated value
 with VALUE.
-This operates by modifying MAP in place.
-If it cannot do that, it signals a `map-not-inplace' error.
+This operates by modifying MAP in place.  If it cannot do that,
+it signals the `map-not-inplace' error.
 To insert an element without modifying MAP, use `map-insert'."
   ;; `testfn' only exists for backward compatibility with `map-put'!
   (declare (advertised-calling-convention (map key value) "27.1")))