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: The poor state of documentation of pcase like things. Date: Wed, 16 Dec 2015 20:26:05 +0000 Message-ID: <20151216202605.GA3752@acm.fritz.box> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1450297472 15963 80.91.229.3 (16 Dec 2015 20:24:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 16 Dec 2015 20:24:32 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Dec 16 21:24:25 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 1a9IcZ-0004GQ-8o for ged-emacs-devel@m.gmane.org; Wed, 16 Dec 2015 21:24:23 +0100 Original-Received: from localhost ([::1]:49247 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9IcY-00055e-Kh for ged-emacs-devel@m.gmane.org; Wed, 16 Dec 2015 15:24:22 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34957) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9IcE-0004xS-5q for emacs-devel@gnu.org; Wed, 16 Dec 2015 15:24:03 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9Ic9-0007bz-3v for emacs-devel@gnu.org; Wed, 16 Dec 2015 15:24:02 -0500 Original-Received: from mail.muc.de ([193.149.48.3]:27148) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9Ic8-0007ba-QW for emacs-devel@gnu.org; Wed, 16 Dec 2015 15:23:57 -0500 Original-Received: (qmail 52130 invoked by uid 3782); 16 Dec 2015 20:23:54 -0000 Original-Received: from acm.muc.de (p548A5E49.dip0.t-ipconnect.de [84.138.94.73]) by colin.muc.de (tmda-ofmipd) with ESMTP; Wed, 16 Dec 2015 21:23:53 +0100 Original-Received: (qmail 20603 invoked by uid 1000); 16 Dec 2015 20:26:05 -0000 Content-Disposition: inline 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:196398 Archived-At: Hello, Emacs. Months after recognising that the documentation of pcase like things is in need of vast improvement, we haven't advanced significantly. 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". 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? (iii) A statement that ` is not ` and , is not ,. (iv) A rigorous specification of what ` and , (and ,@?) mean in pcase patterns. (v) A rigorous specification of when variables get bound, and what they get bound to. (vi) A rigorous specification of when a value matches a pattern. Now, let's have a look a pcase's doc string. It doesn't say what pcase does: "perform ML-style pattern matching" is meaningless to anybody who doesn't know ML-style pattern matching. What it should say is that the value is used to select (at most) one of the CASES, and the forms in that CASE are evaluated - or something like that. 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. 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. -- Alan Mackenzie (Nuremberg, Germany).