bug#46088: 26.3; doc string of `read-regexp'

[Drew Adams]

A. This is unclear, to me:

 If DEFAULTS is a non-nil symbol, then if `read-regexp-defaults-function'
 is non-nil, we use that in place of DEFAULTS in the following:
   If DEFAULTS is the symbol `regexp-history-last', we use the first
   element of HISTORY (if specified) or `regexp-history'.
   If DEFAULTS is a function, we call it with no arguments and use
   what it returns, which should be either nil, a string, or a list of strings.

1. If DEFAULTS is not a non-nil symbol, or if
`read-regexp-defaults-function' is nil, then how to interpret that
"the following" text?  What's it for, in that case?  And if it's not
used in that case, then what if only one of those conditions holds?

2. Assume that `read-regexp-defaults-function' is non-nil - say
`foobar', and DEFAULTS is also a non-nil symbol, say `toto'.

Then DEFAULTS isn't `regexp-history-list', so the first sentence
("If DEFAULTS is the symbol `regexp-history-list') doesn't apply.
Now what if `toto' isn't a function?  What's the behavior?

3. Same thing, exactly, if both `read-regexp-defaults-function' and
DEFAULTS are the same symbol, `foobar'.

4. Assume that DEFAULTS is `regexp-history-last', and
`read-regexp-defaults-function' is a function.  Then the first sentence
applies, so we use the first element of HISTORY or `regexp-history' as
default.  OK.  This particular case is understandable, if hidden in the
jungle.

5. Assume that DEFAULTS is a function and
`read-regexp-defaults-function' is non-nil.  Then the first sentence
doesn't apply, but the second one does: "we call it with no
arguments..."  What's "it"?  DEFAULTS or
`read-regexp-defaults-function'?  (Nowhere does it say that the non-nil
value of the latter should be a function, but let's assume that's the
case, to be generous.)

This doc is impenetrable, to me at least.  There are 4 IFs, 2 of which
seem to be conditioned on the conjunction of the other two:

IF (a AND b) THEN:

 IF...
 IF...

The relations between the two nested IFs aren't clear.  Presumably
there's an ELSE between them, but the overall meaning of this DEFAULTS
description is unclear.

B. And then we get to:

  We append the standard values from `read-regexp-suggestions' to
  DEFAULTS before using it.

  If the first element of DEFAULTS is non-nil (and if PROMPT does not
  end in ":", followed by optional whitespace), we add it to the prompt.

How do you append that to a DEFAULTS value that's a string?  Or a
non-nil symbol?  Or a function?  How can we talk about the elements of a
string, symbol, or function?


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''