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

[Phillip Lord]

Alan Mackenzie <address@hidden> writes:
> 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".

I think it's probably better to make your points (which are reasonable)
without making such aspersions. The author in question has been
extremely generous with their time.


>
> 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?


These defined in terms, but unfortunately, the definition is a bit
recursive -- so a Q-PATTERN is defined in terms of other Q-PATTERNs (or
an atom).


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


I am not 100% convinced that this is a bad thing. The actual semantics
of pcase do mess your head up a bit. The first part, the tutorial
section, is for me one of the clearest sections. I think it's something
that we should have more off, personally.

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

It is indeed worth doing these things.

Phil