master e9591fae5e7 2/3: Add command for teaching Imenu about ERC macros

[F. Jason Park]

branch: master
commit e9591fae5e7ba772b63c6cc548bb5ebe68f583e6
Author: F. Jason Park <jp@neverwas.me>
Commit: F. Jason Park <jp@neverwas.me>

    Add command for teaching Imenu about ERC macros
    
    * lisp/erc/erc-backend.el (define-erc-response-handler): Add
    `doc-string' to `declare' specification.
    * test/lisp/erc/resources/erc-tests-common.el
    (erc-tests-common-add-imenu-expressions): New function for defining and
    undefining Imenu patterns useful to ERC developers.
---
 lisp/erc/erc-backend.el                     |  1 +
 test/lisp/erc/resources/erc-tests-common.el | 37 +++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el
index e72fa036f17..311e3a624e6 100644
--- a/lisp/erc/erc-backend.el
+++ b/lisp/erc/erc-backend.el
@@ -1662,6 +1662,7 @@ Would expand to:
                                   ([&or integerp symbolp]
                                    &rest [&or integerp symbolp])]
                            &optional sexp sexp def-body))
+           (doc-string 2)
            (indent defun))
   (if (numberp name) (setq name (intern (format "%03i" name))))
   (setq aliases (mapcar (lambda (a)
diff --git a/test/lisp/erc/resources/erc-tests-common.el 
b/test/lisp/erc/resources/erc-tests-common.el
index a9495ecb28d..546e74736b0 100644
--- a/test/lisp/erc/resources/erc-tests-common.el
+++ b/test/lisp/erc/resources/erc-tests-common.el
@@ -410,4 +410,41 @@ faces in the reverse order they appear in an inserted 
message."
 
     (funcall test (lambda (arg) (setq faces arg)))))
 
+;; To use this function, add something like
+;;
+;;   ("lisp/erc"
+;;    (emacs-lisp-mode (eval erc-tests-common-add-imenu-expressions)))
+;;
+;; to your ~/emacs/master/.dir-locals-2.el.  Optionally, add the sexp
+;;
+;;   (erc-tests-common-add-imenu-expressions)
+;;
+;; to the user option `safe-local-eval-forms', and load this file before
+;; hacking, possibly by autoloading this function in your init.el.
+(defun erc-tests-common-add-imenu-expressions (&optional removep)
+  "Tell `imenu' about ERC-defined macros.  With REMOVEP, do the opposite."
+  (interactive "P")
+  ;; This currently produces results like "ERC response FOO BAR", but it
+  ;; would be preferable to end up with "erc-response-FOO" and
+  ;; "erc-response-BAR" instead, possibly as separate items.  Likewise
+  ;; for modules: "erc-foo-mode" instead of "ERC module foo".
+  (dolist (item `(("ERC response"
+                   ,(rx bol (* (syntax whitespace))
+                        "(define-erc-response-handler (" (group (+ nonl)) ")")
+                   1)
+                  ("ERC module"
+                   ,(rx bol (* (syntax whitespace))
+                        ;; No `lisp-mode-symbol' in < Emacs 29.
+                        "(define-erc-module " (group (+ (| (syntax word)
+                                                           (syntax symbol)
+                                                           (: "\\" nonl)))))
+                   1)))
+    ;; This should only run in `emacs-lisp-mode' buffers, which have
+    ;; this variable set locally.
+    (cl-assert (local-variable-p 'imenu-generic-expression))
+    (if removep
+        (setq imenu-generic-expression
+              (remove item imenu-generic-expression))
+      (cl-pushnew item imenu-generic-expression :test #'equal))))
+
 (provide 'erc-tests-common)