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

Previous Next

Full log

Message #8 received at 32803 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tino Calancha <tino.calancha <at> gmail.com>
Cc: 32803 <at> debbugs.gnu.org
Subject: Re: 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 <at> gnu.org>
> From: Tino Calancha <tino.calancha <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.