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

[Eric Abrahamsen <eric@ericabrahamsen.net>]

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