1 files changed, 49 insertions, 26 deletions
diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 05d879d8f4b..b0a56492bcd 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -361,34 +361,38 @@ priority but without an overlay face.
                          (flymake-category . flymake-note))))
 @end example
 
-@vindex flymake-text
+@vindex flymake-diagnostics
+@vindex flymake-diagnostic-backend
+@vindex flymake-diagnostic-buffer
+@vindex flymake-diagnostic-text
+@vindex flymake-diagnostic-beg
+@vindex flymake-diagnostic-end
 As you might have guessed, Flymake's annotations are implemented as
 overlays (@pxref{Overlays,,, elisp, The Emacs Lisp Reference Manual}).
 Along with the properties that you specify for the specific type of
-diagnostic, Flymake adds the property @code{flymake-text} to these
-overlays, and sets it to the message string that the backend used to
-describe the diagnostic.
+diagnostic, Flymake adds the property @code{flymake-diagnostic} to
+these overlays, and sets it to the object that the backend created
+with @code{flymake-make-diagnostic}.
 
-Since overlays also support arbitrary keymaps, you can use this
-property @code{flymake-text} to create interactive annotations, such
-as in the following example of binding a @kbd{mouse-3} event (middle
-mouse button click) to an Internet search for the text of a
-@code{:warning} or @code{:error}.
+Since overlays also support arbitrary keymaps, you can use this along
+with the functions @code{flymake-diagnostics} and
+@code{flymake-diagnostic-text} (@pxref{Flymake utility functions}) to
+create interactive annotations, such as in the following example of
+binding a @code{mouse-3} event (middle mouse button click) to an
+Internet search for the text of a @code{:warning} or @code{:error}.
 
 @example
 (defun my-search-for-message (event)
   (interactive "e")
-  (let ((ovs (overlays-at (posn-point (event-start event))))
-        ov)
-    ;; loop until flymake overlay we clicked on is recovered
-    (while (not (overlay-get (setq ov (pop ovs)) 'flymake-text)))
-    (when ov
-      (eww-browse-url
-       (concat "https://duckduckgo.com/?q="
-               (replace-regexp-in-string " "
-                                         "+"
-                                         (overlay-get ov 'flymake-text)))
-       t))))
+  (let* ((diags (flymake-diagnostics (posn-point (event-start event))))
+         (topmost-diag (car diags)))
+    (eww-browse-url
+       (concat
+        "https://duckduckgo.com/?q="
+        (replace-regexp-in-string " "
+                                  "+"
+                                  (flymake-diagnostic-text topmost-diag)))
+       t)))
 
 (dolist (type '(:warning :error))
   (let ((a (assoc type flymake-diagnostic-types-alist)))
@@ -513,6 +517,24 @@ Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to
 of the problem detected in this region.
 @end deffn
 
+@cindex access diagnostic object
+These objects' properties can be accessed with the functions
+@code{flymake-diagnostic-backend}, @code{flymake-diagnostic-buffer},
+@code{flymake-diagnostic-text}, @code{flymake-diagnostic-beg},
+@code{flymake-diagnostic-end} and @code{flymake-diagnostic-type}.
+
+Additionally, the function @code{flymake-diagnostics} will collect
+such objects in the region you specify.
+
+@cindex collect diagnostic objects
+@deffn Function flymake-diagnostics beg end
+Get a list of Flymake diagnostics in the region determined by
+@var{beg} and @var{end}.  If neither @var{beg} or @var{end} is
+supplied, use the whole buffer, otherwise if @var{beg} is
+non-@code{nil} and @var{end} is @code{nil}, consider only diagnostics
+at @var{beg}.
+@end deffn
+
 @cindex buffer position from line and column number
 It is often the case with external syntax tools that a diagnostic's
 position is reported in terms of a line number, and sometimes a column
@@ -520,9 +542,10 @@ number.  To convert this information into a buffer position, backends
 can use the following function:
 
 @deffn Function flymake-diag-region buffer line &optional col
-Compute @var{buffer}'s region (@var{beg} .  @var{end}) corresponding to
-@var{line} and @var{col}.  If @var{col} is nil, return a region just
-for @var{line}.  Return nil if the region is invalid.
+Compute @var{buffer}'s region (@var{beg} .  @var{end}) corresponding
+to @var{line} and @var{col}.  If @var{col} is @code{nil}, return a
+region just for @var{line}.  Return @code{nil} if the region is
+invalid.
 @end deffn
 
 @cindex add a log message
@@ -560,7 +583,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
 
 (defun ruby-flymake (report-fn &rest _args)
   ;; Not having a ruby interpreter is a serious problem which should cause
-  ;; the backend to disable itself, so an @code{error} is signalled.
+  ;; the backend to disable itself, so an @code{error} is signaled.
   ;;
   (unless (executable-find
            "ruby") (error "Cannot find a suitable ruby"))
@@ -600,7 +623,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
                 ;; `ruby--flymake-proc', which indicates that
                 ;; `proc' is not an obsolete process.
                 ;;
-                (if (eq proc ruby--flymake-proc)
+                (if (with-current-buffer source (eq proc ruby--flymake-proc))
                     (with-current-buffer (process-buffer proc)
                       (goto-char (point-min))
                       ;; Parse the output buffer for diagnostic's
@@ -625,7 +648,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active.
                                                         msg)
                        into diags
                        finally (funcall report-fn diags)))
-                  (flymake-log :warning "Cancelling obsolete check %s"
+                  (flymake-log :warning "Canceling obsolete check %s"
                                proc))
               ;; Cleanup the temporary buffer used to hold the
               ;; check's output.