Re: Replace trivial pcase occurrences in the Emacs sources

[Alan Mackenzie <acm@muc.de>]

Hello, Stefan.

On Tue, Oct 30, 2018 at 14:58:58 -0400, Stefan Monnier wrote:
> >> matching doesn't assign any values to anything directly related to
> >> BODY, so the mechanism by which it affects execution of BODY needs
> >> to be described.

> > Could you please fill that void?  This isn't a repetition of what
> > dolist does.

> I don't know how to say it any better than with the patch I just
> installed into emacs-26.

Thank you for this patch, which is excellent.  However, the doc string
for pcase-dolist is still not quite perfect, in that:

1. It doesn't say what the macro does.
2. It doesn't document the arguments to the macro.
3. It appears to refer to an argument which don't exist (VAR).
4. It forces somebody new to Lisp to traverse 5 nodes of the graph of doc
strings (namely pcase-dolist, pcase, dolist, pcase-let, let) and
synthesise these disparate doc strings to get an idea of what the macro
does.  This is too many nodes, and the task is too difficult.
5. It states the macro is equivalent to an expansion of other macros,
which appear no easier to understand than pcase-dolist itself.

Otherwise, not bad!

Are you willing to put these final touches onto pcase-dolist's doc
string, or would you prefer somebody else to do it?

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).