Re: The poor state of documentation of pcase like things.

[Michael Heerdegen <michael_heerdegen@web.de>]

Alan Mackenzie <acm@muc.de> writes:

> Hello, Emacs.

Hello.  (no, I'm not Emacs)

> Months after recognising that the documentation of pcase like things
> is in need of vast improvement, we haven't advanced significantly.

I wished you had not raised this issue so shortly before Christmas.

> We appear to have the following functions/macros: pcase, pcase-let,
> pcase-let*, pcase-codegen, pcase-defmacro, pcase-dolist,
> pcase-exhaustive, and pcase-lambda.
>
> NONE OF THESE, with the exception of pcase itself, IS EVEN MENTIONED IN
> THE ELISP MANUAL.
>
> NONE OF THESE, with the exception of pcase itself, HAS A MEANINGFUL DOC
> STRING.
>
> Some of these doc strings are patronising indeed.  They all seem to say,
> implicitly, "the author's time is far too valuable to waste in writing
> meaningful documentation".

As far as I understand how Stefan used to work, most of the semantics of
most of the pcase derivatives, like `pcase-let', are not yet 100% fixed,
we are not yet sure how useful we are, or if they may later be better be
replaced by other forms that are more general, etc.

IMHO it's good to leave the documentation of the derivatives as is for
now.

>  What do "U" and "Q" stand for?

> There are people on this list who are using pcase like things, and so
> clearly understand their syntax and semantics.  Could these people
> PLEASE document these things, and do so before the release of Emacs
> 25.1.  Preferably well before.

To be honest, I tweaked some of the pcase related documentation, and was
quite happy with it.  I think the pcase docstring is quite good.  A
tutorial is missing though, clearly.


Michael.