Re: Replace trivial pcase occurrences in the Emacs sources

[Alan Mackenzie]

Hello, Stefan.

On Tue, Oct 30, 2018 at 14:17:10 -0400, Stefan Monnier wrote:
> > Not everybody is familiar with dolist by any means.  Is dolist's doc
> > string of sufficiently high quality to act as this basis?

> If dolist's docstring is not good enough, then I don't think it's
> pcase-dolist's job to fix it.

I think everybody would agree with this point.

> >> We do have to keep the reference to `pcase` because we don't want to
> >> repeat the definition of what a pcase pattern can look like.

> > Yes, I think that's right.

> > Things I believe MUST appear explicitly in the doc string for
> > pcase-dolist: 
> > 1. It is a loop over the elements of LIST, which must be a list.
> > 2. It attempts to match the current list element with the supplied
> > PATTERN, which must be a valid pcase style pattern.
> > 3. The BODY forms are evaluated for each element of the list.
> > 4. The purpose of the matching is to create bindings for symbols, and
> > these bindings are in force when the BODY forms are evaluated.
> > 5. When a pattern match fails, ..... (This needs to be stated).

> This is highly redundant w.r.t pcase-let and dolist.

Maybe, but so what?

Doc strings should be as far as is reasonable self contained.  Have a
look at the doc strings for let and let*.  They have a great deal in
common, but each is self contained.

> Fine for the manual, but not for docstrings.

You seem to be arguing that doc strings needn't say what
de{fun,macro,var}s do and are, as long as the meaning can be acquired
through the traversal of a directed acyclic graph of linked doc strings.
Maybe you find this a good way of acquiring information, but I certainly
don't.  I just get angry and frustrated, and I'm sure I'm not the only
one.

> You can click on the link to the docstring of `dolist` and `pcase`
> (tho, I now see the link should go to `pcase-let` instead).

I can, but I'd much rather find the information in a coherent form in a
single place.  That's what doc strings are for.

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).