Minimal tweak as an attempt to future-proof Flymake API

Discussed with Stefan that this should allow Flymake to request more
from backends in the future, while also allowing backends to report
more accurately.

* lisp/progmodes/elisp-mode.el (elisp-flymake-checkdoc)
(elisp-flymake-byte-compile): Adjust to new API.

* lisp/progmodes/flymake-proc.el ()
(flymake-proc-legacy-flymake): Adjust to new API.

* lisp/progmodes/flymake.el (flymake-diagnostic-functions):
Review API again.
(flymake--handle-report): Allow other keys.  Change ACTION to
REPORT-ACTION.

3 files changed, 36 insertions, 26 deletions

diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index f7d2f397672..3690f673832 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1617,7 +1617,7 @@ ARGLIST is either a string, or a list of strings or symbols."
     collected))
 
 ;;;###autoload
-(defun elisp-flymake-checkdoc (report-fn)
+(defun elisp-flymake-checkdoc (report-fn &rest _args)
   "A Flymake backend for `checkdoc'.
 Calls REPORT-FN directly."
   (unless (derived-mode-p 'emacs-lisp-mode)
@@ -1670,7 +1670,7 @@ Calls REPORT-FN directly."
   "Buffer-local process started for byte-compiling the buffer.")
 
 ;;;###autoload
-(defun elisp-flymake-byte-compile (report-fn)
+(defun elisp-flymake-byte-compile (report-fn &rest _args)
   "A Flymake backend for elisp byte compilation.
 Spawn an Emacs process that byte-compiles a file representing the
 current buffer state and calls REPORT-FN when done."
diff --git a/lisp/progmodes/flymake-proc.el b/lisp/progmodes/flymake-proc.el
index b76d18ed313..47ec27f611b 100644
--- a/lisp/progmodes/flymake-proc.el
+++ b/lisp/progmodes/flymake-proc.el
@@ -715,7 +715,7 @@ May only be called in a dynamic environment where
      (flymake-log 1 "Failed to delete dir %s, error ignored" dir-name))))
 
 
-(defun flymake-proc-legacy-flymake (report-fn &optional interactive)
+(defun flymake-proc-legacy-flymake (report-fn &rest args)
   "Flymake backend based on the original Flymake implementation.
 This function is suitable for inclusion in
 `flymake-diagnostic-types-alist'. For backward compatibility, it
@@ -729,8 +729,9 @@ can also be executed interactively independently of
                   (apply (flymake-make-report-fn 'flymake-proc-legacy-flymake)
                          diags
                          (append args '(:force t))))
-                t))
-  (let ((proc flymake-proc--current-process)
+                :interactive t))
+  (let ((interactive (plist-get args :interactive))
+        (proc flymake-proc--current-process)
         (flymake-proc--report-fn report-fn))
     (when (processp proc)
       (process-put proc 'flymake-proc--obsolete t)
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index 48ec361600a..c1a15bf9242 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -320,20 +320,28 @@ Return nil if the region is invalid."
     (error (flymake-error "Invalid region line=%s col=%s" line col))))
 
 (defvar flymake-diagnostic-functions nil
-  "Special hook of Flymake backends to check a buffer.
+  "Special hook of Flymake backends that check a buffer.
 
 The functions in this hook diagnose problems in a buffer’s
-contents and provide the Flymake user interface with information
+contents and provide information to the Flymake user interface
 about where and how to annotate problems diagnosed in a buffer.
 
 Whenever Flymake or the user decides to re-check the buffer, each
-function is called with a common calling convention, a single
-REPORT-FN argument and a list of keword value pairs, detailed
-below.  Backend functions are expected to initiate the buffer
-check, but aren't required to complete it check before exiting:
-if the computation involved is expensive, especially for large
-buffers, that task can be scheduled for the future using
-asynchronous processes or other asynchronous mechanisms.
+function is called with an arbitrary number of arguments:
+
+* the first argument is always REPORT-FN, a callback function
+  detailed below;
+
+* the remaining arguments are keyword-value pairs in the
+  form (:KEY VALUE :KEY2 VALUE2...).  Currently, Flymake provides
+  no such arguments, but backend functions must be prepared to
+  accept to accept and possibly ignore any number of them.
+
+Backend functions are expected to initiate the buffer check, but
+aren't required to complete it check before exiting: if the
+computation involved is expensive, especially for large buffers,
+that task can be scheduled for the future using asynchronous
+processes or other asynchronous mechanisms.
 
 In any case, backend functions are expected to return quickly or
 signal an error, in which case the backend is disabled.  Flymake
@@ -344,10 +352,10 @@ and on again, reset the list of disabled backends.
 If the function returns, Flymake considers the backend to be
 \"running\". If it has not done so already, the backend is
 expected to call the function REPORT-FN with a single argument
-ACTION followed by an optional list of keyword-value pairs
-their values (:KEY1 VALUE1 :KEY2 VALUE2...).
+REPORT-ACTION also followed by an optional list of keyword-value
+pairs in the form (:REPORT-KEY VALUE :REPORT-KEY2 VALUE2...).
 
-The possible values for ACTION are.
+Currently accepted values for REPORT-ACTION are:
 
 * A (possibly empty) list of diagnostic objects created with
   `flymake-make-diagnostic', causing Flymake to annotate the
@@ -365,7 +373,7 @@ The possible values for ACTION are.
 * The symbol `:panic', signalling that the backend has
   encountered an exceptional situation and should be disabled.
 
-The recognized optional keyword arguments are:
+Currently accepted REPORT-KEY arguments are:
 
 * ‘:explanation’: value should give user-readable details of
   the situation encountered, if any.
@@ -544,11 +552,12 @@ present the backend is disabled.")
   "Tell if Flymake has running backends in this buffer"
   (flymake-running-backends))
 
-(cl-defun flymake--handle-report (backend token action
-                                          &key explanation force)
+(cl-defun flymake--handle-report (backend token report-action
+                                          &key explanation force
+                                          &allow-other-keys)
   "Handle reports from BACKEND identified by TOKEN.
 
-BACKEND, ACTION and EXPLANATION, and FORCE conform to the calling
+BACKEND, REPORT-ACTION and EXPLANATION, and FORCE conform to the calling
 convention described in `flymake-diagnostic-functions' (which
 see). Optional FORCE says to handle a report even if TOKEN was
 not expected."
@@ -573,14 +582,14 @@ not expected."
              (not force))
         (flymake-error "Obsolete report from backend %s with explanation %s"
                        backend explanation))
-       ((eq :panic action)
+       ((eq :panic report-action)
         (flymake--disable-backend backend explanation))
-       ((not (listp action))
+       ((not (listp report-action))
         (flymake--disable-backend backend
-                                  (format "Unknown action %S" action))
-        (flymake-error "Expected report, but got unknown key %s" action))
+                                  (format "Unknown action %S" report-action))
+        (flymake-error "Expected report, but got unknown key %s" report-action))
        (t
-        (setq new-diags action)
+        (setq new-diags report-action)
         (save-restriction
           (widen)
           ;; only delete overlays if this is the first report