GNU bug report logs - #32803
26.1.50; cl-do: Add more literature in docstring

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Tino Calancha <tino.calancha <at> gmail.com>
Subject: bug#32803: closed (Re: bug#32803: 26.1.50; cl-do: Add more
 literature in docstring)
Date: Sat, 29 Sep 2018 09:12:02 +0000

[Message part 1 (text/plain, inline)]

Your bug report

#32803: 26.1.50; cl-do: Add more literature in docstring

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 32803 <at> debbugs.gnu.org.

-- 
32803: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=32803
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Tino Calancha <tino.calancha <at> gmail.com>
To: 32803-done <at> debbugs.gnu.org
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Subject: Re: bug#32803: 26.1.50; cl-do: Add more literature in docstring
Date: Sat, 29 Sep 2018 18:10:59 +0900

Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:

>> diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
>> index 10bc611325..b02a917ac0 100644
>> --- a/lisp/emacs-lisp/cl-macs.el
>> +++ b/lisp/emacs-lisp/cl-macs.el
>> @@ -1747,10 +1747,9 @@ cl--loop-build-ands
>>  (defmacro cl-do (steps endtest &rest body)
>>    "Bind variables and run BODY forms until END-TEST returns non-nil.
>>  First, each VAR is bound to the associated INIT value as if by a `let' form.
>> -Then, in each iteration of the loop, the END-TEST is evaluated; if true,
>> -the loop is finished.  Otherwise, the BODY forms are evaluated, then each
>> -VAR is set to the associated STEP expression (as if by a `cl-psetq'
>> -form) and the next iteration begins.
>> +Then, the END-TEST is evaluated; if true, the loop is finished.  Otherwise,
>> +the BODY forms are evaluated, then each VAR is set to the associated
>> +STEP expression (as if by a `cl-psetq' form) and the next iteration begins.
>
> The variable name is endtest, so I guess should be ENDTEST here (no
> hyphen), the same way you've got it later on.
No, we must use the variables exposed to the user: VAR, INIT, STEP,
END-TEST, RESULT, BODY.
Note the last line of the docstring, or try:
M-x describe-function cl-do RET


>> Once the END-TEST becomes true, the RESULT forms are evaluated (with
>>  the VARs still bound to their values) to produce the result
>> @@ -1759,6 +1758,10 @@ cl-do
>>  Note that the entire loop is enclosed in an implicit `nil' block, so
>>  that you can use `cl-return' to exit at any time.
>>  
>> +Also note that the ENDTEST belongs to the iteration; it's always checked
>> +before evaluate BODY.  In particular, if ENDTEST evaluates initially non-nil,
>> +the `cl-do' will end without running BODY.
>
> Some tiny edits here and in the cl-do* docstring:
>
> Also note that ENDTEST is checked before evaluating BODY.  If ENDTEST
> is initially non-nil, `cl-do' will exit without running BODY.
Sounds good.  I will write in this way.  Thank you.

Pushed into emacs-26 branch as commit 'Improve cl-do, cl-do* docstrings'
(7296b6fbf27aeae76ea63ab2d9d9f2e46491b971)

[Message part 3 (message/rfc822, inline)]

From: Tino Calancha <tino.calancha <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.1.50; cl-do: Add more literature in docstring
Date: Sun, 23 Sep 2018 00:02:50 +0900

Severity: wishlist
X-Debbugs-Cc: Eli Zaretskii <eliz <at> gnu.org>

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 <tino.calancha <at> gmail.com>
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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.