From 9e9b78dda94fb1fe0b68f23fc004f87a94e633b5 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 22 Feb 2025 03:41:41 +0100 Subject: [PATCH 1/5] ; Improve lsh and ash documented argument names * doc/lispref/numbers.texi (Bitwise Operations): Improve lsh and ash argument names. --- doc/lispref/numbers.texi | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index fc52f11cf4a..00f47f283b3 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -892,13 +892,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 @@ -967,20 +967,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 -@var{count1} are both negative, the following examples focus on these +As @code{lsh} behaves like @code{ash} except when @var{integer} and +@var{count} are both negative, the following examples focus on these exceptional cases. These examples assume 30-bit fixnums. @smallexample From 3c9b1c3cd18f42dd0cced43b0f1d4c2df9e5cc2d Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 22 Feb 2025 04:16:21 +0100 Subject: [PATCH 2/5] Don't document deleted xwidget functions * doc/lispref/display.texi (Xwidgets): Don't document deleted function xwidget-webkit-execute-script-rv. Fix name of deleted and then re-added function xwidget-webkit-title. --- doc/lispref/display.texi | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index c13c908d3f8..e896b8198af 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -7602,15 +7602,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 -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 +@defun xwidget-webkit-title xwidget This function returns the title of @var{xwidget} as a string. @end defun From 0cc651acddb87180357ab8ff4adcbac8d6174e50 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 22 Feb 2025 14:41:34 +0100 Subject: [PATCH 3/5] ; * admin/check-doc-strings: Add note for future development. --- admin/check-doc-strings | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/admin/check-doc-strings b/admin/check-doc-strings index b119b50885b..dee7ded8237 100755 --- a/admin/check-doc-strings +++ b/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; From e15dcb2db5c40e90ea2a21391af5addb9e778779 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 22 Feb 2025 18:15:37 +0100 Subject: [PATCH 4/5] Improve wording of lsh docstring * lisp/subr.el (lsh): Improve wording of docstring. --- lisp/subr.el | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lisp/subr.el b/lisp/subr.el index 7aca542dab4..7552378a781 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -571,10 +571,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 -to use `ash' instead, unless COUNT could ever be negative, and -if, when COUNT is negative, your program really needs the special -treatment of negative COUNT provided by this function." +Most uses of this function turn out to be mistakes. We recommend using +`ash' instead, unless COUNT could ever be negative, in which case your +program should only use this function if it specifically requires the +special handling of negative COUNT." (declare (ftype (function (integer integer) integer)) (compiler-macro (lambda (form) From 563b6f94511b76266984bc6764ec2a9391448138 Mon Sep 17 00:00:00 2001 From: Vincenzo Pupillo Date: Wed, 22 Jan 2025 16:14:41 +0100 Subject: [PATCH 5/5] Constant highlighting no longer captures Java annotations * lisp/progmodes/java-ts-mode.el (java-ts-mode--fontify-constant): New function. (java-ts-mode--font-lock-settings): Use it. --- lisp/progmodes/java-ts-mode.el | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/lisp/progmodes/java-ts-mode.el b/lisp/progmodes/java-ts-mode.el index 6823cb4f38a..849ab23ef3e 100644 --- a/lisp/progmodes/java-ts-mode.el +++ b/lisp/progmodes/java-ts-mode.el @@ -164,6 +164,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 @@ -174,8 +191,7 @@ the available version of Tree-sitter for Java." :language 'java :override t :feature 'constant - `(((identifier) @font-lock-constant-face - (:match "\\`[A-Z_][0-9A-Z_]*\\'" @font-lock-constant-face)) + `((identifier) @java-ts-mode--fontify-constant [(true) (false)] @font-lock-constant-face) :language 'java :override t