bug#59887: pcase vs. pcase-let: Underscore in backquote-style patterns

[hokomo <hokomo@airmail.cc>]

> That says:
>
> |    The macros described in this section use ‘pcase’ patterns 
> to perform
> | destructuring binding.  The condition of the object to be of 
> compatible
> | structure means that the object must match the pattern, 
> because only
> | then the object’s subfields can be extracted.  For example:
> |
> |        (pcase-let ((`(add ,x ,y) my-list))
> |          (message "Contains %S and %S" x y))
> |
> | does the same as the previous example, except that it directly 
> tries to
> | extract ‘x’ and ‘y’ from ‘my-list’ without first verifying if 
> ‘my-list’
> | is a list which has the right number of elements and has ‘add’ 
> as its
> | first element.  The precise behavior when the object does not 
> actually
> | match the pattern is undefined, although the body will not be 
> silently
> | skipped: either an error is signaled or the body is run with 
> some of the
> | variables potentially bound to arbitrary values like ‘nil’.
>
> That explains the same thing quite broadly.  Maybe you did not 
> notice
> the implications when you first read it?  I dunno, I'm not that 
> good in
> writing documentation, but I can't find something to add from 
> what we
> had discussed that would not be redundant.

That indeed describes it nicely. Somehow I managed to miss that 
whole paragraph and instead skipped directly to the documentation 
string of pcase-let. My bad... :-)

> Or should we maybe just warn about the possible pitfall a bit 
> more
> offensively?

Hmm, I understand the concern about being redundant, especially 
since all four of the listed functions have the same behavior, and 
documenting it for one would mean documenting it for each one.

Perhaps including a variation of the phrase "Each EXP should match 
(i.e. be of compatible structure)" in each of the four 
descriptions would hint at this behavior while not being overly 
verbose? From that point the user can search for "compatible" on 
the same page and immediately find a match in the text at the top 
that explains the constraints.

hokomo