Re: Replace trivial pcase occurrences in the Emacs sources

[Alan Mackenzie <acm@muc.de>]

Hello, Stefan.

On Mon, Oct 29, 2018 at 09:28:25 -0400, Stefan Monnier wrote:
> > Doc strings which specify fully the arguments to these macros, including
> > their semantics, and say what the macros do.  The current doc strings
> > (at least some of them) for these macros don't do this.

> I understand this in theory, but I don't know what it means in this
> concrete case.

Take a look at, for example, the doc string for pcase-dolist.  In its
entirety, it's this:

    pcase-dolist is an autoloaded Lisp macro in `pcase.el'.

    (pcase-dolist (PATTERN LIST) BODY...)

    Like `dolist' but where the binding can be a `pcase' pattern.

There is no clue here what PATTERN, LIST, and BODY mean.  It is unclear
what "the binding" is.  It is unclear, exactly, what a "`pcase' pattern"
is.

It is not explained what the code (generated by the macro) does.  Even
supposing the notion "`pcase' pattern" to be understood, there is no
explanation of how such a pattern is used.

There is no explanation of any compatibility constraints between the
arguments PATTERN, LIST, and BODY.

There are no examples to clarify the syntax and semantics.

Now it is possible that partial enlightenment will come from looking at
the referenced doc strings for dolist and pcase, but I remember,
vaguely, this not being very helpful.  Maybe it's better now, with the
improved documentation of pcase.

> > I've had such questions in the past, and had to answer them by time
> > consuming guessing, reading the source of pcase-..., and
> > experimentation.

> Do you remember them enough to describe the problems, so we can try and
> improve the doc accordingly?

See above.

> > Adequate documentation would have saved me a great deal of time,
> > frustration, and uncertainty.

> I don't doubt it.  But I'm sadly not able to guess what those problems
> might be.

Also see above.

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).