From: Eli Zaretskii <eliz@gnu.org>
To: Tino Calancha <tino.calancha@gmail.com>
Cc: 32803@debbugs.gnu.org
Subject: bug#32803: 26.1.50; cl-do: Add more literature in docstring
Date: Mon, 24 Sep 2018 12:13:46 +0300 [thread overview]
Message-ID: <83ftxzb6lx.fsf@gnu.org> (raw)
In-Reply-To: <87y3bt7exx.fsf@calancha-pc.dy.bbexcite.jp> (message from Tino Calancha on Sun, 23 Sep 2018 00:02:50 +0900)
> 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.
next prev parent reply other threads:[~2018-09-24 9:13 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-09-22 15:02 bug#32803: 26.1.50; cl-do: Add more literature in docstring Tino Calancha
2018-09-24 9:13 ` Eli Zaretskii [this message]
2018-09-24 10:17 ` Tino Calancha
2018-09-24 16:43 ` Eric Abrahamsen
2018-09-24 16:58 ` Eli Zaretskii
2018-09-24 17:53 ` Eric Abrahamsen
2018-09-24 20:43 ` Tino Calancha
2018-09-27 4:08 ` Eric Abrahamsen
2018-09-28 20:13 ` Tino Calancha
2018-09-28 21:00 ` Eric Abrahamsen
2018-09-29 9:10 ` Tino Calancha
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83ftxzb6lx.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=32803@debbugs.gnu.org \
--cc=tino.calancha@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).