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

[Tino Calancha]

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:
--8<-----------------------------cut here---------------start------------->8---
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.
 
 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.
+
 For more details, see `cl-do' description in Info node `(cl) Iteration'.
 
 \(fn ((VAR INIT [STEP])...) (END-TEST [RESULT...]) BODY...)"
@@ -1785,6 +1788,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.
+
 This is to `cl-do' what `let*' is to `let'.
 For more details, see `cl-do*' description in Info node `(cl) Iteration'.
 

--8<-----------------------------cut here---------------end--------------->8---