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

[Tino Calancha]

Eric Abrahamsen <eric@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)