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

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

[Tino Calancha]

Severity: wishlist
X-Debbugs-Cc: Eli Zaretskii <eliz@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@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

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

[Eli Zaretskii]

> Cc: eli zaretskii <eliz@gnu.org>
> From: Tino Calancha <tino.calancha@gmail.com>
> Date: Sun, 23 Sep 2018 00:02:50 +0900
> 
> 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.

Thanks.  My suggestion is to copy the description from the first
paragraph of what the CL manual says.  For example, for cl-do, it says
this:

                                        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.  Once the END-TEST becomes
     true, the RESULT forms are evaluated (with the VARs still bound to
     their values) to produce the result returned by ‘cl-do’.

This could possibly be made less wordy like this:

  Bind VAR initially to INIT.  On each iteration, evaluate END-TEST;
  if nil, evaluate FORMS, set each VAR to the associated STEP
  expression, and perform the next iteration.  When END-TEST becomes
  non-nil, finish the loop and return the result of evaluation of the
  forms in RESULT.

>  (defmacro cl-do (steps endtest &rest body)
> -  "The Common Lisp `do' loop.
> +  "Bind variables and run BODY forms until END-TEST returns non-nil.

The first summary line is very good, please keep it.

I leave it to you to decide whether a link to the Info manual is
needed, after these changes.

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

[Tino Calancha]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: eli zaretskii <eliz@gnu.org>
>> From: Tino Calancha <tino.calancha@gmail.com>
>> Date: Sun, 23 Sep 2018 00:02:50 +0900
>> 
>> 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.
>
> Thanks.  My suggestion is to copy the description from the first
> paragraph of what the CL manual says.
It's very precise.  Thank you.
I just added that the whole loop is wrapped inside a `nil' block.
> I leave it to you to decide whether a link to the Info manual is
> needed, after these changes.
It's worth to keep it so that users can take a look on the
provided examples.

I will push the following in a couple of days in case no more
activity in this thread:
--8<-----------------------------cut here---------------start------------->8---
commit 805adebd1ff999358e016dff8d60751aba657262
Author: Tino Calancha <tino.calancha@gmail.com>
Date:   Mon Sep 24 19:09:29 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..10bc611325 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -1745,7 +1745,21 @@ 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.
+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.
+
+Once the END-TEST becomes true, the RESULT forms are evaluated (with
+the VARs still bound to their values) to produce the result
+returned by `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.
+
+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 +1771,22 @@ 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.
+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 `setq'
+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
+returned by `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.
+
+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 20, x86_64-pc-linux-gnu, GTK+ Version 3.22.11)
Repository revision: 41cdda22c78eb0b00612ce25cdb356dd64322fcc

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

[Eric Abrahamsen]

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

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Cc: eli zaretskii <eliz@gnu.org>
>>> From: Tino Calancha <tino.calancha@gmail.com>
>>> Date: Sun, 23 Sep 2018 00:02:50 +0900
>>> 
>>> 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.
>>
>> Thanks.  My suggestion is to copy the description from the first
>> paragraph of what the CL manual says.
> It's very precise.  Thank you.
> I just added that the whole loop is wrapped inside a `nil' block.
>> I leave it to you to decide whether a link to the Info manual is
>> needed, after these changes.
> It's worth to keep it so that users can take a look on the
> provided examples.
>
> I will push the following in a couple of days in case no more
> activity in this thread:
>
> commit 805adebd1ff999358e016dff8d60751aba657262
> Author: Tino Calancha <tino.calancha@gmail.com>
> Date:   Mon Sep 24 19:09:29 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..10bc611325 100644
> --- a/lisp/emacs-lisp/cl-macs.el
> +++ b/lisp/emacs-lisp/cl-macs.el
> @@ -1745,7 +1745,21 @@ 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.
> +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,
         ^^^^^^^

From the peanut gallery: Without looking at the code, I'm not sure if
this means the test is evaluated *before* BODY (ie, BODY may never run),
or *after* BODY (ie, BODY always runs at least once). Could that "in" be
changed to either "before" or "after"?

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

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  32803@debbugs.gnu.org
> Date: Mon, 24 Sep 2018 09:43:49 -0700
> 
> > +Then, in each iteration of the loop, the END-TEST is evaluated; if true,
>          ^^^^^^^
> 
> >From the peanut gallery: Without looking at the code, I'm not sure if
> this means the test is evaluated *before* BODY (ie, BODY may never run),
> or *after* BODY (ie, BODY always runs at least once).

You've removed the answer to that question.  The full text says:

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

which clearly tells that the test is done _before_ the BODY is run.
Right?

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

[Eric Abrahamsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  32803@debbugs.gnu.org
>> Date: Mon, 24 Sep 2018 09:43:49 -0700
>> 
>> > +Then, in each iteration of the loop, the END-TEST is evaluated; if true,
>>          ^^^^^^^
>> 
>> >From the peanut gallery: Without looking at the code, I'm not sure if
>> this means the test is evaluated *before* BODY (ie, BODY may never run),
>> or *after* BODY (ie, BODY always runs at least once).
>
> You've removed the answer to that question.  The full text says:
>
>                                                           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 [...]
>
> which clearly tells that the test is done _before_ the BODY is run.
> Right?

I guess you're right, yes. "In" still seems unnecessarily vague, though,
when it could simply be replaced with "before". But not that big a deal,
I guess.

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

[Tino Calancha]

On Mon, 24 Sep 2018, Eric Abrahamsen wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>>> Cc: Eli Zaretskii <eliz@gnu.org>,  32803@debbugs.gnu.org
>>> Date: Mon, 24 Sep 2018 09:43:49 -0700
>>>
>>>> +Then, in each iteration of the loop, the END-TEST is evaluated; if true,
>>>          ^^^^^^^
>>>
>>>> From the peanut gallery: Without looking at the code, I'm not sure if
>>> this means the test is evaluated *before* BODY (ie, BODY may never run),
>>> or *after* BODY (ie, BODY always runs at least once).
>>
>> You've removed the answer to that question.  The full text says:
>>
>>                                                           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 [...]
>>
>> which clearly tells that the test is done _before_ the BODY is run.
>> Right?
>
> I guess you're right, yes. "In" still seems unnecessarily vague, though,
> when it could simply be replaced with "before". But not that big a deal,
> I guess.
Thank you for the feedback Eric.
In some sense, the endtest is part of the loop, that's why the "in".
It behaves similar like this:

[initialize/update VARS]
(if endtest
   (return RESULT)
  body)


I am OK to rephrase it to make it more obvious if you have something
in mind.
Some people learning CL complaint about this iteration as been weird.
I see it as a generalization of a `dolist'.  Paul Graham build many tools
on top of this.

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

[Eric Abrahamsen]

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

> On Mon, 24 Sep 2018, Eric Abrahamsen wrote:
>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>>>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>>>> Cc: Eli Zaretskii <eliz@gnu.org>,  32803@debbugs.gnu.org
>>>> Date: Mon, 24 Sep 2018 09:43:49 -0700
>>>>
>>>>> +Then, in each iteration of the loop, the END-TEST is evaluated; if true,
>>>>          ^^^^^^^
>>>>
>>>>> From the peanut gallery: Without looking at the code, I'm not sure if
>>>> this means the test is evaluated *before* BODY (ie, BODY may never run),
>>>> or *after* BODY (ie, BODY always runs at least once).
>>>
>>> You've removed the answer to that question.  The full text says:
>>>
>>>                                                           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 [...]
>>>
>>> which clearly tells that the test is done _before_ the BODY is run.
>>> Right?
>>
>> I guess you're right, yes. "In" still seems unnecessarily vague, though,
>> when it could simply be replaced with "before". But not that big a deal,
>> I guess.
> Thank you for the feedback Eric.
> In some sense, the endtest is part of the loop, that's why the "in".
> It behaves similar like this:
>
> [initialize/update VARS]
> (if endtest
>   (return RESULT)
>  body)
>
>
> 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".

It really doesn't matter all that much.

Thanks,
Eric

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

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

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)