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

[Alan Mackenzie]

Hello, Michael.

On Sat, Dec 19, 2015 at 04:26:52PM +0100, Michael Heerdegen wrote:
> Alan Mackenzie <address@hidden> writes:

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

My level of frustration and annoyance is steadily rising despite the
imminence of Yuletide.  I wish you a happy one, though.

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

Yet the said functions have been committed on the release branch and are
already in widespread use throughout the Emacs sources.  As Eli notes,
there're around 90 uses of pcase-let and pcase-let*.  I count 18
occurrences of pcase-dolist outside of pcase.el.  And so on.

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

They're essentially undocumented.  That makes the code that uses them
essentially unmaintainable, except by those who know, or are prepared to
guess, what these functions do.  I can't agree with you that this is
good.

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

The pcase docstring is getting better, yes.  It stil doesn't document
explicitly that the normal meanings of ` and , are suspended.  There is
still no explicit statement of what pcase's ` and , mean.

Maybe I'm expecting too much, and ` and , have no intrinsic meanings in
pcase.  But I don't believe that is the case.  

> Michael.

-- 
Alan Mackenzie (Nuremberg, Germany).