bug#64656: 29.0.91; Doc of minibuffer histories and completing-read - automatic addition of completions to DEFAULT list

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Sat, 15 Jul 2023 23:35:20 +0000
> 
> It seems to me that the doc, including in the Elisp manual, doesn't make
> clear that, by default, `completing-read' automatically adds the list of
> all completions provided by the completion table to the list of
> defaults, just after the default value.  That is, by default, it calls
> `minibuffer-default-add-completions'.
> 
> This is not obvious from reading the docs.  For example, it's not
> obvious that if you use `C-h v' and then `M-p', repeating `M-p, you get
> the symbols that are variables, one by one, inserted into the
> minibuffer.
> 
> How so?  Because by default variable `minibuffer-default-add-function'
> is `minibuffer-default-add-completions'.  Again, none of this is
> obvious.  To find it out, a user needs to check what `M-p' is bound to,
> then check the source code for that function, and then the source code
> or the doc string of function `goto-history-element', which it calls.
> 
> In sum, important user-visible behavior isn't described in the manual or
> the "top-level", most-relevant doc strings (e.g. `completing-read').

You have described various aspects of the implementation, but no
"user-visible behavior" and no reason why it would be interesting, let
alone important, to have that in the manual.  Please consider changing
the POV of your description so that it will be clear what important
information is missing and why.  The main purpose of API descriptions
in the ELisp manual is to explain to Lisp programmers how to achieve
this or that behavior, and I cannot bridge the gap between that goal
and what you wrote.

For starters, this:

  It seems to me that the doc, including in the Elisp manual, doesn't make
  clear that, by default, `completing-read' automatically adds the list of
  all completions provided by the completion table to the list of
  defaults, just after the default value.  That is, by default, it calls
  `minibuffer-default-add-completions'.

is a huge turn-off, because it talks about what the code does.  After
reading this, I have no idea why I would need to know these details.
Why do I care that the list of all completions is added to the list of
defaults? why do I care that the code calls
minibuffer-default-add-completions?  Etc. etc.