Merge from origin/emacs-30

563b6f9451 Constant highlighting no longer captures Java annotations
e15dcb2db5 Improve wording of lsh docstring
0cc651acdd ; * admin/check-doc-strings: Add note for future developm...
3c9b1c3cd1 Don't document deleted xwidget functions
9e9b78dda9 ; Improve lsh and ash documented argument names

admin/check-doc-strings

@@ -5,6 +5,18 @@ eval 'exec perl -S $0 "$@"' # Portability kludge
 # Author: Martin Buchholz
 # This program is in the public domain.
 
+# NOTE ADDED 2025-02-22:
+#
+# This is an old script that doesn't necessarily work very well with
+# today's sources.  If anyone wants to fix it up, it might be worth the
+# effort, as it could help catch some mistakes that we have overlooked.
+#
+# If you want to work on this, consider fundamentally rethinking the
+# approach.  Instead of flagging anything that *might* be an error,
+# maybe it should flag only things that we are *sure* are an error.
+# That would make it possible to run this as a matter of routine, just
+# as we already do with codespell (see "admin/run-codespell").
+
 use strict;
 use warnings;
 use POSIX;

doc/lispref/display.texi

@@ -7606,15 +7606,7 @@ This function causes the browser widget specified by @var{xwidget} to
 execute the specified JavaScript @code{script}.
 @end defun
 
-@defun xwidget-webkit-execute-script-rv xwidget script &optional default
+@defun xwidget-webkit-title xwidget
-This function executes the specified @var{script} like
-@code{xwidget-webkit-execute-script} does, but it also returns the
-script's return value as a string.  If @var{script} doesn't return a
-value, this function returns @var{default}, or @code{nil} if
-@var{default} was omitted.
-@end defun
-
-@defun xwidget-webkit-get-title xwidget
 This function returns the title of @var{xwidget} as a string.
 @end defun
 

doc/lispref/numbers.texi

@@ -927,13 +927,13 @@ reproducing the same pattern moved over.
 
   The bitwise operations in Emacs Lisp apply only to integers.
 
-@defun ash integer1 count
+@defun ash integer count
 @cindex arithmetic shift
-@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1}
+@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer}
 to the left @var{count} places, or to the right if @var{count} is
 negative.  Left shifts introduce zero bits on the right; right shifts
 discard the rightmost bits.  Considered as an integer operation,
-@code{ash} multiplies @var{integer1} by
+@code{ash} multiplies @var{integer} by
 @ifnottex
 2**@var{count},
 @end ifnottex
@@ -1002,20 +1002,20 @@ Here are examples of shifting left or right by two bits:
 @end smallexample
 @end defun
 
-@defun lsh integer1 count
+@defun lsh integer count
 @cindex logical shift
 @code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the
-bits in @var{integer1} to the left @var{count} places, or to the right
+bits in @var{integer} to the left @var{count} places, or to the right
 if @var{count} is negative, bringing zeros into the vacated bits.  If
-@var{count} is negative, then @var{integer1} must be either a fixnum
+@var{count} is negative, then @var{integer} must be either a fixnum
 or a positive bignum, and @code{lsh} treats a negative fixnum as if it
 were unsigned by subtracting twice @code{most-negative-fixnum} before
 shifting, producing a nonnegative result.  This quirky behavior dates
 back to when Emacs supported only fixnums; nowadays @code{ash} is a
 better choice.
 
-As @code{lsh} behaves like @code{ash} except when @var{integer1} and
+As @code{lsh} behaves like @code{ash} except when @var{integer} and
-@var{count1} are both negative, the following examples focus on these
+@var{count} are both negative, the following examples focus on these
 exceptional cases.  These examples assume 30-bit fixnums.
 
 @smallexample

lisp/progmodes/java-ts-mode.el

@@ -179,6 +179,23 @@ the available version of Tree-sitter for Java."
     (error
      `((string_literal) @font-lock-string-face))))
 
+(defun java-ts-mode--fontify-constant (node override start end &rest _)
+  "Fontify a Java constant.
+In Java the names of variables declared class constants and of ANSI
+constants should be all uppercase with words separated by underscores.
+This function also prevents annotations from being highlighted as if
+they were constants.
+For NODE, OVERRIDE, START, and END, see `treesit-font-lock-rules'."
+  (let ((node-start (treesit-node-start node))
+	(case-fold-search nil))
+    (when (and
+	   (not (equal (char-before node-start) ?@)) ;; skip annotations
+	   (string-match "\\`[A-Z_][0-9A-Z_]*\\'" (treesit-node-text node)))
+      (treesit-fontify-with-override
+       node-start (treesit-node-end node)
+       'font-lock-constant-face override
+       start end))))
+
 (defvar java-ts-mode--font-lock-settings
   (treesit-font-lock-rules
    :language 'java
@@ -189,8 +206,7 @@ the available version of Tree-sitter for Java."
    :language 'java
    :override t
    :feature 'constant
-   `(((identifier) @font-lock-constant-face
+   `((identifier) @java-ts-mode--fontify-constant
-      (:match "\\`[A-Z_][0-9A-Z_]*\\'" @font-lock-constant-face))
      [(true) (false)] @font-lock-constant-face)
    :language 'java
    :override t

lisp/subr.el

@@ -601,10 +601,10 @@ If COUNT is negative, shifting is actually to the right.
 In this case, if VALUE is a negative fixnum treat it as unsigned,
 i.e., subtract 2 * `most-negative-fixnum' from VALUE before shifting it.
 
-Most uses of this function turn out to be mistakes.  We recommend
+Most uses of this function turn out to be mistakes.  We recommend using
-to use `ash' instead, unless COUNT could ever be negative, and
+`ash' instead, unless COUNT could ever be negative, in which case your
-if, when COUNT is negative, your program really needs the special
+program should only use this function if it specifically requires the
-treatment of negative COUNT provided by this function."
+special handling of negative COUNT."
   (declare (ftype (function (integer integer) integer))
            (compiler-macro
             (lambda (form)