[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#32803: 26.1.50; cl-do: Add more literature in docstring
From: |
Eli Zaretskii |
Subject: |
bug#32803: 26.1.50; cl-do: Add more literature in docstring |
Date: |
Mon, 24 Sep 2018 12:13:46 +0300 |
> 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, 2018/09/22
- bug#32803: 26.1.50; cl-do: Add more literature in docstring,
Eli Zaretskii <=
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eli Zaretskii, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/24
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/27
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/28
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Eric Abrahamsen, 2018/09/28
- bug#32803: 26.1.50; cl-do: Add more literature in docstring, Tino Calancha, 2018/09/29