From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: The poor state of documentation of pcase like things. Date: Sat, 19 Dec 2015 18:30:57 +0000 Message-ID: <20151219183057.GA2238@acm.fritz.box> References: <20151216202605.GA3752@acm.fritz.box> <87fuyytq6b.fsf@web.de> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1450549748 25933 80.91.229.3 (19 Dec 2015 18:29:08 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 19 Dec 2015 18:29:08 +0000 (UTC) Cc: emacs-devel@gnu.org To: Michael Heerdegen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 19 19:29:00 2015 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aAMFY-0007Y5-1r for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 19:29:00 +0100 Original-Received: from localhost ([::1]:38238 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAMFX-00015K-Fs for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 13:28:59 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38065) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAMFT-00014x-RE for emacs-devel@gnu.org; Sat, 19 Dec 2015 13:28:56 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aAMFO-0007rI-SB for emacs-devel@gnu.org; Sat, 19 Dec 2015 13:28:55 -0500 Original-Received: from mail.muc.de ([193.149.48.3]:41451) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAMFO-0007rA-Iq for emacs-devel@gnu.org; Sat, 19 Dec 2015 13:28:50 -0500 Original-Received: (qmail 7748 invoked by uid 3782); 19 Dec 2015 18:28:48 -0000 Original-Received: from acm.muc.de (p5B146D78.dip0.t-ipconnect.de [91.20.109.120]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sat, 19 Dec 2015 19:28:43 +0100 Original-Received: (qmail 2436 invoked by uid 1000); 19 Dec 2015 18:30:57 -0000 Content-Disposition: inline In-Reply-To: <87fuyytq6b.fsf@web.de> User-Agent: Mutt/1.5.23 (2014-03-12) X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x X-Received-From: 193.149.48.3 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:196518 Archived-At: Hello, Michael. On Sat, Dec 19, 2015 at 04:26:52PM +0100, Michael Heerdegen wrote: > Alan Mackenzie 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).