The poor state of documentation of pcase like things.

[Alan Mackenzie]

Hello, Emacs.

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

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".

Particularly egregious is the doc string for pcase-exhaustive: "The
exhaustive version of `pcase' (which see).".  Uhh????  Needless to say,
the doc string of pcase makes no mention of "exhaustive".

Let us analyse the documentation of the one macro which is documented to
any meaningful extent, pcase itself:

The article in the Elisp manual for pcase starts well, documenting the
basic form and outlining the basic semantics, but then starts rambling
on like a tutorial, rather than filling in the semantic details.  Here
is a partial list of what is missing from that manual page:

(i) A @dfn{U-PATTERN}.
(ii) A @dfn{Q-PATTERN}.
These two things are described only in terms of their structure, not
what they are conceptually.  What do "U" and "Q" stand for?  What is the
semantic significance of a Q-PATTERN?
(iii) A statement that ` is not ` and , is not ,.
(iv) A rigorous specification of what ` and , (and ,@?) mean in pcase
patterns.
(v) A rigorous specification of when variables get bound, and what they
get bound to.
(vi) A rigorous specification of when a value matches a pattern.

Now, let's have a look a pcase's doc string.  It doesn't say what pcase
does: "perform ML-style pattern matching" is meaningless to anybody who
doesn't know ML-style pattern matching.  What it should say is that the
value is used to select (at most) one of the CASES, and the forms in
that CASE are evaluated - or something like that.

It would appear that Lisp programmers are expected to absorb the
semantics (and sometimes even the syntax) of pcase-* by osmosis:
studying and imitating examples.  This is a Bad Thing.

Most (?all) of the rest of Emacs Lisp is effectively and rigorously
documented.  For example, both the Elisp manual entry and the doc string
for cond are effective.

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.

-- 
Alan Mackenzie (Nuremberg, Germany).