Offer the Member in class: prompt to be easily skipped under ido-mode (#3501)

Author: vemv

CHANGELOG.md

@@ -58,6 +58,7 @@
 - Always match friendly sessions for `cider-ancillary-buffers` (like `*cider-error*`, `*cider-result*`, etc).
 - `cider-test`: only show diffs for collections.
 - `cider-inspector-def-current-val` now can suggest a var name (default none), which can be customized via `cider-inspector-preferred-var-names`.
+- The "Member in class: " prompt can now be optionally skipped in ido-mode by pressing `<up>` or `<down>` ([doc](https://docs.cider.mx/cider/usage/code_completion.html)).
 - [#3375](https://github.com/clojure-emacs/cider/pull/3375): `cider-test`: don't render a newline between expected and actual, most times.
 - Interactive evaluation: show a shorter overlay when rendering compilation errors.
   - e.g., the `Syntax error compiling clojure.core/let at (foo/bar.clj:10:1)` prefix is now removed.

cider-client.el

@@ -474,6 +474,38 @@ itself is present."
   (with-current-buffer (cider-current-repl)
     nrepl-tooling-session))
 
+(declare-function ido-exit-minibuffer "ido" t)
+
+;; Not used anywhere, except in documentation as a suggestion for users.
+(defmacro cider--with-temporary-ido-keys (UP DOWN &rest body)
+  "Temporarily define UP, DOWN keys for ido and execute BODY.
+
+This makes the UX for auto-completion more streamlined,
+since one often wants to go to the next candidate (DOWN key)
+without having to specify a Java class for the current candidate
+\(because the current candidate may be irrelevant to the user)."
+  `(if (bound-and-true-p ido-common-completion-map)
+       (let ((original-up-binding (lookup-key ido-common-completion-map (kbd ,UP)))
+             (original-down-binding (lookup-key ido-common-completion-map (kbd ,DOWN))))
+         (define-key ido-common-completion-map (kbd ,UP) (lambda ()
+                                                           (interactive)
+                                                           (ido-exit-minibuffer)))
+         (define-key ido-common-completion-map (kbd ,DOWN) (lambda ()
+                                                             (interactive)
+                                                             (ido-exit-minibuffer)))
+         (unwind-protect
+             (progn ,@body)
+           (define-key ido-common-completion-map (kbd ,UP) original-up-binding)
+           (define-key ido-common-completion-map (kbd ,DOWN) original-down-binding)))
+     ,@body))
+
+(defun cider-class-choice-completing-read (prompt candidates)
+  "A completing read that can be customized with the `advice' mechanism,
+forwarding PROMPT and CANDIDATES as-is.
+
+See also: `cider--with-temporary-ido-keys'."
+  (completing-read prompt candidates))
+
 (defun cider--var-choice (var-info)
   "Prompt to choose from among multiple VAR-INFO candidates, if required.
 This is needed only when the symbol queried is an unqualified host platform
@@ -482,7 +514,7 @@ contain a `candidates' key, it is returned as is."
   (let ((candidates (nrepl-dict-get var-info "candidates")))
     (if candidates
         (let* ((classes (nrepl-dict-keys candidates))
-               (choice (completing-read "Member in class: " classes nil t))
+               (choice (cider-class-choice-completing-read "Member in class: " classes))
                (info (nrepl-dict-get candidates choice)))
           info)
       var-info)))

doc/modules/ROOT/pages/usage/code_completion.adoc

@@ -150,6 +150,26 @@ image::completion-annotations.png[Completion Annotations]
 TIP: Completion annotations can be disabled by setting
 `cider-annotate-completion-candidates` to `nil`.
 
+=== Notes on class disambiguation
+
+Sometimes, the completion user experience may be interrupted by a `completing-read`
+that asks for the `Member in class`. This is used for better Java completions and documentation.
+
+However, if you are not interested in the current candidate, disambiguating it is of no use,
+and the prompt can be a nuisance.
+
+If you are using Company for completions and IDO for `completing-read`, you can cause the `<up>` and `<down>`
+keys to cancel the prompt by customizing:
+
+[source,lisp]
+----
+(advice-add 'cider-class-choice-completing-read
+            :around
+            (lambda (f a b)
+              (cider--with-temporary-ido-keys "<up>" "<down>"
+                (funcall f a b))))
+----
+
 === Changing the completion style
 
 Sometimes the user may want to use a different completion style just for the CIDER