Add cider-jump-to-pop-to-buffer-actions

Provide a means to control what window to use when jumping to a definition with
`cider-jump-to`.

By default, always use current window.

This fixes clojure-emacs#2499

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New features
 
+* [#2499](https://github.com/clojure-emacs/cider/issues/2499): Add `cider-jump-to-pop-to-buffer-actions`.
 * [#2738](https://github.com/clojure-emacs/cider/pull/2738): Add ability to lookup a function symbol when cursor is at the opening paren.
 * [#2735](https://github.com/clojure-emacs/cider/pull/2735): New debugger command `P` to inspect an arbitrary expression, it was previously bound to `p` which now inspects the current value.
 * [#2729](https://github.com/clojure-emacs/cider/pull/2729): New cider inspector command `cider-inspector-def-current-val` lets you define a var with the current inspector value.

cider-common.el

@@ -127,6 +127,18 @@ On failure, read a symbol name using PROMPT and call CALLBACK with that."
 
 (declare-function cider-mode "cider-mode")
 
+(defcustom cider-jump-to-pop-to-buffer-actions
+  '((display-buffer-same-window))
+  "Determines what window `cider-jump-to` uses.
+The value is passed as the `action` argument to `pop-to-buffer`.
+
+The default value means always use the current window.
+
+For further details, see https://docs.cider.mx/cider/repl/configuration.html#_control_what_window_to_use_when_jumping_to_a_definition"
+  :type 'sexp
+  :group 'cider
+  :package-version '(cider . "0.24.0"))
+
 (defun cider-jump-to (buffer &optional pos other-window)
   "Push current point onto marker ring, and jump to BUFFER and POS.
 POS can be either a number, a cons, or a symbol.
@@ -139,8 +151,7 @@ If OTHER-WINDOW is non-nil don't reuse current window."
     (ring-insert find-tag-marker-ring (point-marker)))
   (if other-window
       (pop-to-buffer buffer 'display-buffer-pop-up-window)
-    ;; like switch-to-buffer, but reuse existing window if BUFFER is visible
-    (pop-to-buffer buffer '((display-buffer-reuse-window display-buffer-same-window))))
+    (pop-to-buffer buffer cider-jump-to-pop-to-buffer-actions))
   (with-current-buffer buffer
     (widen)
     (goto-char (point-min))

doc/modules/ROOT/pages/repl/configuration.adoc

@@ -261,3 +261,47 @@ can set:
 ----
 (setq cider-repl-require-ns-on-set t)
 ----
+
+== Control what window to use when jumping to a definition
+
+By default kbd:[M-.] and other commands that jump to a definition use the current
+window to show the definition.
+
+Other behaviour is possible, and is controlled with
+`cider-jump-to-pop-to-buffer-actions`; the value of this is passed as the
+`action` argument to `pop-to-buffer`.
+
+The default value is `\((display-buffer-same-window))`; this means to always use
+the current window.
+
+An alternative is to use an existing window in the current frame when there is
+one that is showing the target buffer. If you want this behaviour, set:
+
+[source,lisp]
+----
+(setq cider-jump-to-pop-to-buffer-actions
+      '((display-buffer-reuse-window display-buffer-same-window)))
+----
+
+For other possibilities, see the documentation for `display-buffer`.
+
+=== Example 1
+
+You jump to `map` in core.clj when core.clj *_is not_* being displayed in another
+window in the current frame.
+
+With both the default behaviour and the alternative behaviour defined above, the
+definition of `map` will be shown in the current window.
+
+=== Example 2
+
+You jump to `map` in core.clj when core.clj *_is_* being displayed in another window
+in the current frame.
+
+With the default behaviour, the definition of `map` will be shown in the current
+window; you will now have two windows showing core.clj, and the existing
+core.clj window will be unchanged.
+
+With the alternative behaviour defined above, the definition of `map` will be
+shown in the existing core.clj window; all windows will show the same buffer as
+before the jump, and the current window will now be the one showing core.clj.