[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Phillip Lord
Subject: Re: The poor state of documentation of pcase like things.
Date: Thu, 17 Dec 2015 13:59:56 +0000
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux)

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]