From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Replace trivial pcase occurrences in the Emacs sources Date: Mon, 29 Oct 2018 13:47:22 +0000 Message-ID: <20181029134722.GC4195@ACM> References: <83tvlcsnee.fsf@gnu.org> <86mur137n8.fsf@gmail.com> <20181029130132.GB4195@ACM> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1540821937 300 195.159.176.226 (29 Oct 2018 14:05:37 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 29 Oct 2018 14:05:37 +0000 (UTC) User-Agent: Mutt/1.10.1 (2018-07-13) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 29 15:05:33 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gH8Ae-0008Op-T4 for ged-emacs-devel@m.gmane.org; Mon, 29 Oct 2018 15:05:32 +0100 Original-Received: from localhost ([::1]:45830 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gH8Cl-0003hT-6w for ged-emacs-devel@m.gmane.org; Mon, 29 Oct 2018 10:07:43 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37933) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gH82Y-0003xc-AA for emacs-devel@gnu.org; Mon, 29 Oct 2018 09:57:11 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gH82U-0003cy-UX for emacs-devel@gnu.org; Mon, 29 Oct 2018 09:57:10 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:32399 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1gH82U-0003bV-Kh for emacs-devel@gnu.org; Mon, 29 Oct 2018 09:57:06 -0400 Original-Received: (qmail 44766 invoked by uid 3782); 29 Oct 2018 13:57:05 -0000 Original-Received: from acm.muc.de (p5B1478E3.dip0.t-ipconnect.de [91.20.120.227]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 29 Oct 2018 14:57:04 +0100 Original-Received: (qmail 6176 invoked by uid 1000); 29 Oct 2018 13:47:22 -0000 Content-Disposition: inline In-Reply-To: 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 [fuzzy] X-Received-From: 193.149.48.1 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:230766 Archived-At: Hello, Stefan. On Mon, Oct 29, 2018 at 09:28:25 -0400, Stefan Monnier wrote: > > Doc strings which specify fully the arguments to these macros, including > > their semantics, and say what the macros do. The current doc strings > > (at least some of them) for these macros don't do this. > I understand this in theory, but I don't know what it means in this > concrete case. Take a look at, for example, the doc string for pcase-dolist. In its entirety, it's this: pcase-dolist is an autoloaded Lisp macro in `pcase.el'. (pcase-dolist (PATTERN LIST) BODY...) Like `dolist' but where the binding can be a `pcase' pattern. There is no clue here what PATTERN, LIST, and BODY mean. It is unclear what "the binding" is. It is unclear, exactly, what a "`pcase' pattern" is. It is not explained what the code (generated by the macro) does. Even supposing the notion "`pcase' pattern" to be understood, there is no explanation of how such a pattern is used. There is no explanation of any compatibility constraints between the arguments PATTERN, LIST, and BODY. There are no examples to clarify the syntax and semantics. Now it is possible that partial enlightenment will come from looking at the referenced doc strings for dolist and pcase, but I remember, vaguely, this not being very helpful. Maybe it's better now, with the improved documentation of pcase. > > I've had such questions in the past, and had to answer them by time > > consuming guessing, reading the source of pcase-..., and > > experimentation. > Do you remember them enough to describe the problems, so we can try and > improve the doc accordingly? See above. > > Adequate documentation would have saved me a great deal of time, > > frustration, and uncertainty. > I don't doubt it. But I'm sadly not able to guess what those problems > might be. Also see above. > Stefan -- Alan Mackenzie (Nuremberg, Germany).