(display-buffer-overriding-action): Try and discourage abuse

* lisp/window.el (display-buffer-overriding-action): Document
the intended use in the deluded hope to reduce the current abuse.

1 files changed, 7 insertions, 2 deletions

diff --git a/lisp/window.el b/lisp/window.el
index af5d73d3384..6a35e553bb9 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -8026,9 +8026,14 @@ See `display-buffer' for details.
 This variable is not intended for user customization.  Lisp
 programs should never set this variable permanently but may bind
 it around calls of buffer display functions like `display-buffer'
-or `pop-to-buffer'.  Since such a binding will affect any nested
+or `pop-to-buffer'.
+
+Since such a binding will affect unconditionally any nested
 buffer display requests, this variable should be used with utmost
-care.")
+care, typically in response to an explicit request by the user.
+Also, any code that sets this variable needs to interact nicely with
+other code that sets this variable.
+See `other-frame-prefix' for an example of use.")
 (put 'display-buffer-overriding-action 'risky-local-variable t)
 
 (defcustom display-buffer-alist nil