From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31311: 27.0; doc of `pcase' Date: Sun, 29 Apr 2018 15:59:24 -0700 (PDT) Message-ID: <4875e9e0-0f6b-433d-a50d-9125d8370740@default> References: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1525042729 15814 195.159.176.226 (29 Apr 2018 22:58:49 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 29 Apr 2018 22:58:49 +0000 (UTC) To: 31311@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Apr 30 00:58:45 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1fCvHI-0003yR-Az for geb-bug-gnu-emacs@m.gmane.org; Mon, 30 Apr 2018 00:58:44 +0200 Original-Received: from localhost ([::1]:57123 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCvJP-0004hO-AR for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 19:00:55 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42836) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCvJ2-0004bJ-Un for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 19:00:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fCvIZ-0005RP-Dn for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 19:00:32 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35352) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fCvIZ-0005RE-6V for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 19:00:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fCvIY-0003eM-QK for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 19:00:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 29 Apr 2018 23:00:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31311 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31311-submit@debbugs.gnu.org id=B31311.152504277713965 (code B ref 31311); Sun, 29 Apr 2018 23:00:02 +0000 Original-Received: (at 31311) by debbugs.gnu.org; 29 Apr 2018 22:59:37 +0000 Original-Received: from localhost ([127.0.0.1]:43249 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCvI8-0003dB-Of for submit@debbugs.gnu.org; Sun, 29 Apr 2018 18:59:36 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:57086) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCvI6-0003cv-JB for 31311@debbugs.gnu.org; Sun, 29 Apr 2018 18:59:35 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w3TMuHHS134781 for <31311@debbugs.gnu.org>; Sun, 29 Apr 2018 22:59:28 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=71MUKb5++6dXchA0jo7J6dQLYTbzeR/v9Ikn8xU3RUc=; b=meJGsdWV+wHRF1mJqsLfIi8h9RP0fjrqAp2qUTVct/mUgzFpqLWhYPTKNLlBhjtko60R dGHSCUqrGa7naTmVYUerbi3rX7T46EV256c6S826LgVLVU4M0Yg8dS8mUQ9JGGW4m0lx ssCyO72btsI2poPH5ZxgpvyHPH/vr/TmofrF2yY3upEUUtLGiBs6PVWqIpXymOk1NXCO C2GFxzL38RzqM1KmesayXY4E6oVJWAAh529QgsZk4imcd0jS4MoffgD3dcQUGBM2V0Ob jAieKhdICOtNy0joIVlkXp0GbNfnTO5ukUwjuThllcz07Cd6J4k+OI4fqqISSHjOgl4e rA== Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp2120.oracle.com with ESMTP id 2hmgxfj5ug-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for <31311@debbugs.gnu.org>; Sun, 29 Apr 2018 22:59:28 +0000 Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w3TMxRKk030521 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for <31311@debbugs.gnu.org>; Sun, 29 Apr 2018 22:59:27 GMT Original-Received: from abhmp0001.oracle.com (abhmp0001.oracle.com [141.146.116.7]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w3TMxRgo007348 for <31311@debbugs.gnu.org>; Sun, 29 Apr 2018 22:59:27 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4678.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8878 signatures=668698 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=13 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1804290231 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:145844 Archived-At: 1. Even just the first line of the doc string seems wrong: "Evaluate EXP and attempt to match it against structural patterns." That should be something more like this: "Evaluate EXP and match _its value_ against structural patterns." It does not match EXP ("it") against the patterns. It matches the result of evaluating EXP (against the patterns). (And are the patterns necessarily "structural"?) I'd say: "Evaluate EXP and match its value against CASES." Even better would be to call the second arg PATTERNS. "Evaluate EXP and match its value against PATTERNS." This is especially so because after that we talk only about "patterns", never referring to CASES. 2. CODE is undefined (not specified). We say only this: "The CODE expression corresponding to the matching pattern determines the return value." So CODE must be an expression (Aha!). That should be said up front. But what does "_corresponding_ to the matching pattern" mean? 3. And just _how_ does the CODE expression that corresponds to the matching pattern "determine the return value"? The rest of the doc string never mentions the return value at all, AFAICT. It mentions neither "return" nor "value". [There is one occurrence of "return", but it is about something different: "(pred FUN) matches if FUN applied to the object returns non-nil."] The rest of the doc string (before the extra, unclear generated text) just talks about the available standard patterns and how matching is done - nothing about what value is returned by the code resulting from `pcase' macro expansion. Even if we can't get someone super-knowledgable about `pcase' to work on the doc, perhaps some rudimentary improvement can be made.