[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.
Phil
- Re: The poor state of documentation of pcase like things., (continued)
- Re: The poor state of documentation of pcase like things., John Wiegley, 2015/12/22
- Re: The poor state of documentation of pcase like things., Michael Heerdegen, 2015/12/19
- Re: The poor state of documentation of pcase like things., Eli Zaretskii, 2015/12/19
- Re: The poor state of documentation of pcase like things., Michael Heerdegen, 2015/12/19
- Re: The poor state of documentation of pcase like things., John Wiegley, 2015/12/22
- Re: The poor state of documentation of pcase like things., Phillip Lord, 2015/12/19
- Re: The poor state of documentation of pcase like things., Michael Heerdegen, 2015/12/19
- Re: The poor state of documentation of pcase like things., Phillip Lord, 2015/12/19
- Re: The poor state of documentation of pcase like things., Michael Heerdegen, 2015/12/20
RE: The poor state of documentation of pcase like things., Drew Adams, 2015/12/16
Re: The poor state of documentation of pcase like things.,
Phillip Lord <=
Re: The poor state of documentation of pcase like things., Michael Heerdegen, 2015/12/19
Re: The poor state of documentation of pcase like things., Eli Zaretskii, 2015/12/19
Re: The poor state of documentation of pcase like things., Alan Mackenzie, 2015/12/19