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

Previous Next

Full log

Message #37 received at 32803-done <at> debbugs.gnu.org (full text, mbox):

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)

Previous Next

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