master 50f430ebcd8 6/6: Clarify purpose of module aliases in ERC

[F. Jason Park]

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

    Clarify purpose of module aliases in ERC
    
    * doc/misc/erc.texi: Mention that aliases should not be defined for
    new modules.
    * lisp/erc/erc-common.el (define-erc-module): Refactor slightly for
    readability.
    (erc-with-all-buffers-of-server): Redo doc string.
    * lisp/erc/erc-pcomplete.el: Declare `completion' module's feature and
    group as being `erc-pcomplete'.
    * test/lisp/erc/erc-tests.el (erc--find-group--real): Assert group
    lookup works for "normalized" module name `completion' of
    `erc-pcomplete-mode'.
---
 doc/misc/erc.texi          |  8 ++++++++
 lisp/erc/erc-common.el     | 31 +++++++++++++++++--------------
 lisp/erc/erc-pcomplete.el  |  2 ++
 test/lisp/erc/erc-tests.el |  1 +
 4 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index 52c7477c9dd..f877fb681fe 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -678,6 +678,14 @@ signals an error.  Users defining personal modules in an 
init file
 should @code{(provide 'erc-my-module)} somewhere to placate ERC.
 Dynamically generating modules on the fly is not supported.
 
+Some older built-in modules have a second name along with a second
+minor-mode toggle, which is just a function alias for its primary
+counterpart.  For practical reasons, ERC does not define a
+corresponding variable alias because contending with indirect
+variables complicates bookkeeping tasks, such as persisting module
+state across IRC sessions.  New modules should definitely avoid
+defining aliases without a good reason.
+
 Some packages have been known to autoload a module's definition
 instead of its minor-mode command, which severs the link between the
 library and the module.  This means that enabling the mode by invoking
diff --git a/lisp/erc/erc-common.el b/lisp/erc/erc-common.el
index 2581e40f850..28ab6aad466 100644
--- a/lisp/erc/erc-common.el
+++ b/lisp/erc/erc-common.el
@@ -333,6 +333,7 @@ instead of a `set' state, which precludes any actual 
saving."
     (read (current-buffer))))
 
 (defmacro erc--find-feature (name alias)
+  ;; Don't use this outside of the file that defines NAME.
   `(pcase (erc--find-group ',name ,(and alias (list 'quote alias)))
      ('erc (and-let* ((file (or (macroexp-file-name) buffer-file-name)))
              (intern (file-name-base file))))
@@ -350,8 +351,12 @@ See Info node `(elisp) Defining Minor Modes' for more.")
 (defmacro define-erc-module (name alias doc enable-body disable-body
                                   &optional local-p)
   "Define a new minor mode using ERC conventions.
-Symbol NAME is the name of the module.
-Symbol ALIAS is the alias to use, or nil.
+Expect NAME to be the module's name and ALIAS, when non-nil, to
+be a retired name used only for compatibility purposes.  In new
+code, assume NAME is the same symbol users should specify when
+customizing `erc-modules' (see info node `(erc) Module Loading'
+for more on naming).
+
 DOC is the documentation string to use for the minor mode.
 ENABLE-BODY is a list of expressions used to enable the mode.
 DISABLE-BODY is a list of expressions used to disable the mode.
@@ -382,7 +387,10 @@ Example:
   (let* ((sn (symbol-name name))
          (mode (intern (format "erc-%s-mode" (downcase sn))))
          (enable (intern (format "erc-%s-enable" (downcase sn))))
-         (disable (intern (format "erc-%s-disable" (downcase sn)))))
+         (disable (intern (format "erc-%s-disable" (downcase sn))))
+         (nmodule (erc--normalize-module-symbol name))
+         (amod (and alias (intern (format "erc-%s-mode"
+                                          (downcase (symbol-name alias)))))))
     `(progn
        (define-minor-mode
          ,mode
@@ -399,13 +407,9 @@ if ARG is omitted or nil.
            (if ,mode (,enable) (,disable))))
        ,(erc--assemble-toggle local-p name enable mode t enable-body)
        ,(erc--assemble-toggle local-p name disable mode nil disable-body)
-       ,@(and-let* ((alias)
-                    ((not (eq name alias)))
-                    (aname (intern (format "erc-%s-mode"
-                                           (downcase (symbol-name alias))))))
-           `((defalias ',aname #',mode)
-             (put ',aname 'erc-module ',(erc--normalize-module-symbol name))))
-       (put ',mode 'erc-module ',(erc--normalize-module-symbol name))
+       ,@(and amod `((defalias ',amod #',mode)
+                     (put ',amod 'erc-module ',nmodule)))
+       (put ',mode 'erc-module ',nmodule)
        ;; For find-function and find-variable.
        (put ',mode    'definition-name ',name)
        (put ',enable  'definition-name ',name)
@@ -462,10 +466,9 @@ If no server buffer exists, return nil."
              ,@body)))))
 
 (defmacro erc-with-all-buffers-of-server (process pred &rest forms)
-  "Execute FORMS in all buffers which have same process as this server.
-FORMS will be evaluated in all buffers having the process PROCESS and
-where PRED matches or in all buffers of the server process if PRED is
-nil."
+  "Evaluate FORMS in all buffers of PROCESS in which PRED returns non-nil.
+When PROCESS is nil, do so in all ERC buffers.  When PRED is nil,
+run FORMS unconditionally."
   (declare (indent 2) (debug (form form body)))
   (macroexp-let2 nil pred pred
     `(erc-buffer-filter (lambda ()
diff --git a/lisp/erc/erc-pcomplete.el b/lisp/erc/erc-pcomplete.el
index 52ebdc83e5e..05cbaf3872f 100644
--- a/lisp/erc/erc-pcomplete.el
+++ b/lisp/erc/erc-pcomplete.el
@@ -58,7 +58,9 @@ add this string to nicks completed."
 
 ;;;###autoload(put 'Completion 'erc--module 'completion)
 ;;;###autoload(put 'pcomplete 'erc--module 'completion)
+;;;###autoload(put 'completion 'erc--feature 'erc-pcomplete)
 ;;;###autoload(autoload 'erc-completion-mode "erc-pcomplete" nil t)
+(put 'completion 'erc-group 'erc-pcomplete)
 (define-erc-module pcomplete Completion
   "In ERC Completion mode, the TAB key does completion whenever possible."
   ((add-hook 'erc-mode-hook #'pcomplete-erc-setup)
diff --git a/test/lisp/erc/erc-tests.el b/test/lisp/erc/erc-tests.el
index a71cc806f6a..2318fed28f2 100644
--- a/test/lisp/erc/erc-tests.el
+++ b/test/lisp/erc/erc-tests.el
@@ -3186,6 +3186,7 @@
   (should (eq (erc--find-group 'autojoin) 'erc-autojoin))
   (should (eq (erc--find-group 'pcomplete 'Completion) 'erc-pcomplete))
   (should (eq (erc--find-group 'capab-identify) 'erc-capab))
+  (should (eq (erc--find-group 'completion) 'erc-pcomplete))
   ;; No group specified.
   (should (eq (erc--find-group 'smiley nil) 'erc))
   (should (eq (erc--find-group 'unmorse nil) 'erc)))