1 files changed, 21 insertions, 13 deletions

diff --git a/lisp/icomplete.el b/lisp/icomplete.el
index c1d9556e24d..875c41bd841 100644
--- a/lisp/icomplete.el
+++ b/lisp/icomplete.el
@@ -79,11 +79,12 @@ selection process starts again from the user's $HOME."
 (defcustom icomplete-show-matches-on-no-input nil
   "When non-nil, show completions when first prompting for input.
 This means to show completions even when the current minibuffer contents
-is the same as was the initial input after minibuffer activation.
-This also means that if you traverse the list of completions with
-commands like \\`C-.' and just hit \\`RET' without typing any
-characters, the match under point will be chosen instead of the
-default."
+is the same as the initial input after minibuffer activation.
+This also means that if you just hit \\`C-j' without typing any
+characters, this chooses the first completion candidate instead of the
+minibuffer's default value.
+
+See also `icomplete-ret'."
   :type 'boolean
   :version "24.4")
 
@@ -242,16 +243,25 @@ Used to implement the option `icomplete-show-matches-on-no-input'.")
   :doc "Keymap used by `icomplete-mode' in the minibuffer."
   "C-M-i" #'icomplete-force-complete
   "C-j"   #'icomplete-force-complete-and-exit
-  "M-j"   #'icomplete-exit
   "C-."   #'icomplete-forward-completions
-  "C-,"   #'icomplete-backward-completions
-  "<remap> <minibuffer-complete-and-exit>" #'icomplete-ret)
+  "C-,"   #'icomplete-backward-completions)
 
 (defun icomplete-ret ()
-  "Exit minibuffer for icomplete."
+  "Alternative minibuffer exit for Icomplete.
+If there is a completion candidate and the minibuffer contents is the
+same as it was right after minibuffer activation, exit selecting that
+candidate.  Otherwise do as `minibuffer-complete-and-exit'.
+
+You may wish to consider binding this command to \\`RET' (or to
+`<remap> <minibuffer-complete-and-exit>') in `icomplete-minibuffer-map'.
+If you do that, then when Emacs first prompts for input such that the
+current minibuffer contents is equal to the initial input right after
+minibuffer activation, \\`RET' chooses the first completion candidate
+instead of the minibuffer's default value.
+This rebinding is especially useful if you have customized
+`icomplete-show-matches-on-no-input' to a non-nil value."
   (interactive)
-  (if (and icomplete-show-matches-on-no-input
-           (car completion-all-sorted-completions)
+  (if (and (car completion-all-sorted-completions)
            (equal (icomplete--field-string) icomplete--initial-input))
       (icomplete-force-complete-and-exit)
     (minibuffer-complete-and-exit)))
@@ -456,8 +466,6 @@ if that doesn't produce a completion match."
       (minibuffer-complete-and-exit)
     (exit-minibuffer)))
 
-(defalias 'icomplete-exit #'icomplete-fido-exit)
-
 (defun icomplete-fido-backward-updir ()
   "Delete char before or go up directory, like `ido-mode'."
   (interactive)