emacs-29 9dfccb89fc: Clarify bug-reference-auto-setup-functions docstring.

[Tassilo Horn]

branch: emacs-29
commit 9dfccb89fc576c89f48a89c95203c3bd68194154
Author: Tassilo Horn <tsdh@gnu.org>
Commit: Tassilo Horn <tsdh@gnu.org>

    Clarify bug-reference-auto-setup-functions docstring.
    
    * lisp/progmodes/bug-reference.el (bug-reference-auto-setup-functions):
    Add clarification to docstring that this variable is for packages, not
    for users.
---
 lisp/progmodes/bug-reference.el | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/lisp/progmodes/bug-reference.el b/lisp/progmodes/bug-reference.el
index 2c5378fcbb..9f1439e6a0 100644
--- a/lisp/progmodes/bug-reference.el
+++ b/lisp/progmodes/bug-reference.el
@@ -611,7 +611,21 @@ guesswork is based on these variables:
 - `bug-reference-setup-from-mail-alist' for guessing based on
   mail group names or mail header values.
 - `bug-reference-setup-from-irc-alist' for guessing based on IRC
-  channel or network names.")
+  channel or network names.
+
+Note: This variable's purpose is to allow packages to provide
+bug-reference auto-setup support in buffers managed by this
+package.  Therefore, such auto-setup function should check if the
+current buffer is \"their\" buffer and only act if that's the
+case, e.g., in terms of `derived-mode-p'.
+
+The variable is not intended for users.  Those are advised to set
+`bug-reference-bug-regexp' and `bug-reference-url-format' using
+other means such as file-local variable sections, a
+`.dir-locals.el' file, or compute and set their values in
+`bug-reference-mode-hook' or `bug-reference-prog-mode-hook'.  If
+the bug regexp and URL format are already set after those hooks
+have been run, the auto-setup is inhibited.")
 
 ;; Add the default auto-setup functions.  We don't have them as
 ;; init value of bug-reference-auto-setup-functions because then