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

[Eric Abrahamsen]

Tino Calancha <tino.calancha@gmail.com> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>> I am OK to rephrase it to make it more obvious if you have something
>>> in mind.
>>
>> I don't have a serious objection! It just seems to me that the key
>> question about any test-and-loop construct is: does it test first, or
>> loop first? As Eli points out, the rest of the docstring makes it clear
>> that it tests first. It just seems to me that nothing is lost (and
>> something gained) by replacing "in" with "before".
> Thank you Eric.
> I agree with you that such info is crucial.  Indeed, in my first
> version of the patch I included the line:
> "On each iteration, check END-TEST before run BODY."
>
> I think is worth to remark that.
> Following patch applies on top of the previous one:

Thanks for doing this! I have nitpicks :)

> commit c057715eff519114e38d82d39b16d8f2a01c3c4d
> Author: Tino Calancha <tino.calancha@gmail.com>
> Date:   Sat Sep 29 05:05:59 2018 +0900
>
>     Clarify that ENDTEST belongs to the iteration
>
> 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.

> 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.

That's pretty pedantic, but I'm an editor and can't help it :) Thanks
for your clarification of these docs!

Eric