Discourage ill-defined use of buffer targets in ERC

* lisp/erc/erc.el (erc-default-recipients, erc-default-target):
Explain that the variable has fallen out of favor and that the
function may have been used historically by third-party code for
detecting channel subscription status, even though that's never been
the case internally since at least the adoption of version control.
Recommend newer alternatives.

(erc--current-buffer-joined-p): Add possibly temporary predicate for
detecting whether a buffer's target is a joined channel.  The existing
means are inconsistent, as discussed in bug#48598.  The mere fact that
they are disparate is unfriendly to new contributors.  For example, in
the function `erc-autojoin-channels', the `process-status' of the
`erc-server-process' is used to detect whether a buffer needs joining.
That's fine in that specific situation, but it won't work elsewhere.
And neither will checking whether `erc-default-target' is nil, so
long as `erc-delete-default-channel' and friends remain in play.

(erc-add-default-channel, erc-delete-default-channel, erc-add-query,
erc-delete-query): Deprecate these helpers, which rely on an unused
usage variant of `erc-default-recipients'.

* lisp/erc/erc-services.el: remove stray `erc-default-recipients'
declaration.

* lisp/erc/erc-backend.el (erc-server-NICK, erc-server-JOIN,
erc-server-KICK, erc-server-PART): wrap deprecated helpers to suppress
warnings.

* lisp/erc/erc-join.el (erc-autojoin-channels): Use helper to detect
whether a buffer needs joining.  Prefer this to server liveliness, as
explained above.

1 files changed, 40 insertions, 1 deletions

diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 078a446a1c3..9f17816b8d4 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -1907,6 +1907,21 @@ all channel buffers on all servers."
 
 ;; Some local variables
 
+;; TODO eventually deprecate this variable
+;;
+;; In the ancient, pre-CVS days (prior to June 2001), this list may
+;; have been used for supporting the changing of a buffer's target on
+;; the fly (mid-session).  Such usage, which allowed cons cells like
+;; (QUERY . bob) to serve as the list's head, was either never fully
+;; integrated or was partially clobbered prior to the introduction of
+;; version control.  But vestiges remain (see `erc-dcc-chat-mode').
+;; And despite appearances, no evidence has emerged that ERC ever
+;; supported one-to-many target buffers.  If such a thing was aspired
+;; to, it was never realized.
+;;
+;; New library code should use the `erc--target' struct instead.
+;; Third-party code can continue to use this until a getter for
+;; `erc--target' (or whatever replaces it) is exported.
 (defvar-local erc-default-recipients nil
   "List of default recipients of the current buffer.")
 
@@ -5868,6 +5883,27 @@ See also `erc-downcase'."
 
 ;; default target handling
 
+(defun erc--current-buffer-joined-p ()
+  "Return whether the current target buffer is joined."
+  ;; This may be a reliable means of detecting subscription status,
+  ;; but it's also roundabout and awkward.  Perhaps it's worth
+  ;; discussing adding a joined slot to `erc--target' for this.
+  (cl-assert erc--target)
+  (and (erc--target-channel-p erc--target)
+       (erc-get-channel-user (erc-current-nick)) t))
+
+;; This function happens to return nil in channel buffers previously
+;; parted or those from which a user had been kicked.  While this
+;; "works" for detecting whether a channel is currently subscribed to,
+;; new code should consider using
+;;
+;;   (erc-get-channel-user (erc-current-nick))
+;;
+;; instead.  For retrieving a target regardless of subscription or
+;; connection status, use replacements based on `erc--target'.
+;; (Coming soon.)
+;;
+;; TODO deprecate this
 (defun erc-default-target ()
   "Return the current default target (as a character string) or nil if none."
   (let ((tgt (car erc-default-recipients)))
@@ -5878,12 +5914,14 @@ See also `erc-downcase'."
 
 (defun erc-add-default-channel (channel)
   "Add CHANNEL to the default channel list."
+  (declare (obsolete "use `erc-cmd-JOIN' or similar instead" "29.1"))
   (let ((chl (downcase channel)))
     (setq erc-default-recipients
           (cons chl erc-default-recipients))))
 
 (defun erc-delete-default-channel (channel &optional buffer)
   "Delete CHANNEL from the default channel list."
+  (declare (obsolete "use `erc-cmd-PART' or similar instead" "29.1"))
   (with-current-buffer (if (and buffer
                                 (bufferp buffer))
                            buffer
@@ -5895,6 +5933,7 @@ See also `erc-downcase'."
   "Add QUERY'd NICKNAME to the default channel list.
 
 The previous default target of QUERY type gets removed."
+  (declare (obsolete "use `erc-cmd-QUERY' or similar instead" "29.1"))
   (let ((d1 (car erc-default-recipients))
         (d2 (cdr erc-default-recipients))
         (qt (cons 'QUERY (downcase nickname))))
@@ -5905,7 +5944,7 @@ The previous default target of QUERY type gets removed."
 
 (defun erc-delete-query ()
   "Delete the topmost target if it is a QUERY."
-
+  (declare (obsolete "use one query buffer per target instead" "29.1"))
   (let ((d1 (car erc-default-recipients))
         (d2 (cdr erc-default-recipients)))
     (if (and (listp d1)