From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Tino Calancha Newsgroups: gmane.emacs.bugs Subject: bug#32803: 26.1.50; cl-do: Add more literature in docstring Date: Sun, 23 Sep 2018 00:02:50 +0900 Message-ID: <87y3bt7exx.fsf@calancha-pc.dy.bbexcite.jp> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1537628533 28919 195.159.176.226 (22 Sep 2018 15:02:13 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 22 Sep 2018 15:02:13 +0000 (UTC) To: 32803@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Sep 22 17:02:09 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 1g3jQ7-0007Uc-OG for geb-bug-gnu-emacs@m.gmane.org; Sat, 22 Sep 2018 17:02:07 +0200 Original-Received: from localhost ([::1]:35642 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3jSD-00063G-RE for geb-bug-gnu-emacs@m.gmane.org; Sat, 22 Sep 2018 11:04:17 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54947) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3jS2-00063B-9X for bug-gnu-emacs@gnu.org; Sat, 22 Sep 2018 11:04:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3jRy-0007qJ-VI for bug-gnu-emacs@gnu.org; Sat, 22 Sep 2018 11:04:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:45480) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1g3jRy-0007pe-Q8; Sat, 22 Sep 2018 11:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1g3jRy-0004KU-KD; Sat, 22 Sep 2018 11:04:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Tino Calancha Original-Sender: "Debbugs-submit" Resent-CC: eliz@gnu.org, bug-gnu-emacs@gnu.org Resent-Date: Sat, 22 Sep 2018 15:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 32803 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org X-Debbugs-Original-Xcc: eli zaretskii Original-Received: via spool by submit@debbugs.gnu.org id=B.153762860816593 (code B ref -1); Sat, 22 Sep 2018 15:04:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 22 Sep 2018 15:03:28 +0000 Original-Received: from localhost ([127.0.0.1]:49738 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3jRQ-0004JY-1B for submit@debbugs.gnu.org; Sat, 22 Sep 2018 11:03:28 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:33836) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1g3jRO-0004JI-EZ for submit@debbugs.gnu.org; Sat, 22 Sep 2018 11:03:26 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3jRH-0006xT-4f for submit@debbugs.gnu.org; Sat, 22 Sep 2018 11:03:20 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:51161) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g3jRF-0006vw-M8 for submit@debbugs.gnu.org; Sat, 22 Sep 2018 11:03:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54814) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g3jRE-00060q-RY for bug-gnu-emacs@gnu.org; Sat, 22 Sep 2018 11:03:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g3jR9-0006qU-UL for bug-gnu-emacs@gnu.org; Sat, 22 Sep 2018 11:03:15 -0400 Original-Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:44108) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1g3jR8-0006mU-Iq for bug-gnu-emacs@gnu.org; Sat, 22 Sep 2018 11:03:11 -0400 Original-Received: by mail-wr1-x436.google.com with SMTP id v16-v6so15524504wro.11 for ; Sat, 22 Sep 2018 08:03:09 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id:mime-version; bh=Ext1476mDGTBBqKAPq/8TXduEI44Lyx3Nj72A9WojgM=; b=o8s0/vSBpTwyhNRX6MODSjiPfzbl2kWaE/xHgc9RB5XHoow4c7zhC6MTE7gO35CAdH TKerqrG/9eWfedRefHr6KX6VHf0TiggW1hie2yCFo+i54al/W3Cs5i+L1Xq6N6Ft/f0L SmNdpravgEuX4Gp/PRCrhBWwD4KEhuS1qCXNVBRz4QCTUD0VTtaT0oTcDNu+exDCxdGj JxnLlLMSBZdk96QTg2sh2VmrrH0XaAHYLRmOvlXxW/7nW1NOkrugMEgNl+PR+BvytcCI 4vuYKYyVTfzD/X/35av9697+4sNCxF/EsyzPYWsMouK1Sef+E8U9F1h/5FiI30NjfPAA qVkg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version; bh=Ext1476mDGTBBqKAPq/8TXduEI44Lyx3Nj72A9WojgM=; b=jFvI8FQVKMgFLrip/nf21c2jIhriHk+kybcQ5LgWm+PxYrdWi/TsjRuspy+skITaTf eQicY7nLNVPDZ6Y3nGwiaknodjYww0k+222aXJwvsYvB+lO5Lol4GqpnOo8+fGrFBUeo buQYXLf3iKvrETzULwoRH91mE4PNpilrMRY6m9ajQTY7cn06TsDt529+H+8SPkkTmOFx j4Y9eiOTFn7EexQgk+V110NMvL2jK3Ye08jCkZloTeGNX22bTGbp/yxG5fv9DBEgv6BC /G9gGu64oa0Wz2UTKWPo2Hfw3nd7Sl1J7IDt1wsN34rWJkYhM30qd6S7tT6MnhTfalfs xDeA== X-Gm-Message-State: ABuFfohd8dLcTy9HkaEUiAerEQWMb0BL3lDQCOyZuAW/qkxICH2spnG4 jsNE+R4C8P7fqEWzvljfNRhr6+33 X-Google-Smtp-Source: ACcGV60FayB+aLTBHLLa5j6wzsfxsrIl6C9zawiL9u+0xHfyy6He4bWY3ZKle22LlpLUvnzd/gIHHQ== X-Received: by 2002:adf:93c2:: with SMTP id 60-v6mr2034482wrp.81.1537628588185; Sat, 22 Sep 2018 08:03:08 -0700 (PDT) Original-Received: from calancha-pc.dy.bbexcite.jp (15.red-83-50-151.dynamicip.rima-tde.net. [83.50.151.15]) by smtp.gmail.com with ESMTPSA id x10-v6sm748027wmi.31.2018.09.22.08.03.06 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sat, 22 Sep 2018 08:03:07 -0700 (PDT) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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:150548 Archived-At: Severity: wishlist X-Debbugs-Cc: Eli Zaretskii Well, the subject say everything... the docstring of cl-do/cl-do* resembles one of my phone calls :-( Considering their names (do), it might be useful talk a bit about what the macros do :-) There is also room to say something on their arguments. We could add a link to the proper info manual node as well, as in the `cl-loop' docstring. --8<-----------------------------cut here---------------start------------->8--- commit 026e683f999a5ad3958dc133fe2a46863a00afe8 Author: Tino Calancha Date: Sat Sep 22 23:45:31 2018 +0900 * lisp/emacs-lisp/cl-macs.el(cl-do, cl-do*): Update docstring diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el index 0854e665b9..20c9fa454d 100644 --- a/lisp/emacs-lisp/cl-macs.el +++ b/lisp/emacs-lisp/cl-macs.el @@ -1745,7 +1745,14 @@ cl--loop-build-ands ;;;###autoload (defmacro cl-do (steps endtest &rest body) - "The Common Lisp `do' loop. + "Bind variables and run BODY forms until END-TEST returns non-nil. +Bind VAR initially to INIT; on successive iterations update VAR + with STEP form. +On each iteration, check END-TEST before run BODY. +Return RESULT, default nil. + +This is the Common Lisp `do' loop. +For more details, see `cl-do' description in Info node `(cl) Iteration'. \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)" (declare (indent 2) @@ -1757,7 +1764,14 @@ cl-do ;;;###autoload (defmacro cl-do* (steps endtest &rest body) - "The Common Lisp `do*' loop. + "Bind variables and run BODY forms until END-TEST returns non-nil. +Bind VAR initially to INIT; on successive iterations update VAR + with STEP form. +On each iteration, check END-TEST before run BODY. +Return RESULT, default nil. + +This is to `cl-do' what `let*' is to `let'. +For more details, see `cl-do*' description in Info node `(cl) Iteration'. \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)" (declare (indent 2) (debug cl-do)) --8<-----------------------------cut here---------------end--------------->8--- In GNU Emacs 26.1.50 (build 16, x86_64-pc-linux-gnu, GTK+ Version 3.22.11) Repository revision: 41cdda22c78eb0b00612ce25cdb356dd64322fcc