dotimes-with-progress-reporter doc string lacks SPEC

dotimes-with-progress-reporter doc string lacks SPEC

[Lennart Borgman]

I think I can guess what the doc string for this function means, but it 
would be more easy if SPEC where explicitly explained.

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Paul Pogonyshev]

Lennart Borgman wrote:
> I think I can guess what the doc string for this function means, but it 
> would be more easy if SPEC where explicitly explained.

Well, the same applies to `dotimes'.

Paul

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Mathias Dahl]

> Well, the same applies to `dotimes'.

This is interesting. Here is the source for the `dotimes' macro:

(defmacro dotimes (spec &rest body)
  "Loop a certain number of times.
Evaluate BODY with VAR bound to successive integers from 0, inclusive,
to COUNT, exclusive.  Then evaluate RESULT to get return value, default
nil.

\(fn (VAR COUNT [RESULT]) BODY...)"
  (let ((temp (make-symbol "--cl-dotimes-temp--")))
    (list 'block nil
	  (list* 'let (list (list temp (nth 1 spec)) (list (car spec) 0))
		 (list* 'while (list '< (car spec) temp)
			(append body (list (list 'incf (car spec)))))
		 (or (cdr (cdr spec)) '(nil))))))

It mentiones `spec', which I think Lennart wants to know more about.

When loaded (or is it compiled?) though (I just made a dummy call to
it), the documentation string says this:

dotimes is a Lisp macro in `cl-macs'.
(dotimes (VAR COUNT [RESULT]) BODY...)

Loop a certain number of times.
Evaluate BODY with VAR bound to successive integers from 0, inclusive,
to COUNT, exclusive.  Then evaluate RESULT to get return value, default
nil.

Not mentioning any `spec' at all.

Anyone care to explain this magic?

Re: dotimes-with-progress-reporter doc string lacks SPEC

[David Kastrup]

"Mathias Dahl" <mathias.dahl@gmail.com> writes:

>> Well, the same applies to `dotimes'.
>
> This is interesting. Here is the source for the `dotimes' macro:
>
> (defmacro dotimes (spec &rest body)
>  "Loop a certain number of times.
> Evaluate BODY with VAR bound to successive integers from 0, inclusive,
> to COUNT, exclusive.  Then evaluate RESULT to get return value, default
> nil.
>
> \(fn (VAR COUNT [RESULT]) BODY...)"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> When loaded (or is it compiled?) though (I just made a dummy call to
> it), the documentation string says this:
>
> dotimes is a Lisp macro in `cl-macs'.
> (dotimes (VAR COUNT [RESULT]) BODY...)

> Not mentioning any `spec' at all.
>
> Anyone care to explain this magic?

See above.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Lennart Borgman]

Mathias Dahl wrote:
>> Well, the same applies to `dotimes'.
>
> This is interesting. Here is the source for the `dotimes' macro:
>
> (defmacro dotimes (spec &rest body)
>  "Loop a certain number of times.
> Evaluate BODY with VAR bound to successive integers from 0, inclusive,
> to COUNT, exclusive.  Then evaluate RESULT to get return value, default
> nil.
>
> \(fn (VAR COUNT [RESULT]) BODY...)"
>  (let ((temp (make-symbol "--cl-dotimes-temp--")))
>    (list 'block nil
>       (list* 'let (list (list temp (nth 1 spec)) (list (car spec) 0))
>          (list* 'while (list '< (car spec) temp)
>             (append body (list (list 'incf (car spec)))))
>          (or (cdr (cdr spec)) '(nil))))))
>
> It mentiones `spec', which I think Lennart wants to know more about.
>
> When loaded (or is it compiled?) though (I just made a dummy call to
> it), the documentation string says this:
>
> dotimes is a Lisp macro in `cl-macs'.
> (dotimes (VAR COUNT [RESULT]) BODY...)
>
> Loop a certain number of times.
> Evaluate BODY with VAR bound to successive integers from 0, inclusive,
> to COUNT, exclusive.  Then evaluate RESULT to get return value, default
> nil.
>
> Not mentioning any `spec' at all.
>
> Anyone care to explain this magic?

Hm, thanks. I can see the pattern. Searching elisp Info I found the 
explanation in "(elisp) Function Documentation":

   The last line of the documentation string can specify calling
   conventions different from the actual function arguments.  Write text
  like this:

     \(fn ARGLIST)

  ...

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Mathias Dahl]

> Hm, thanks. I can see the pattern. Searching elisp Info I found the
> explanation in "(elisp) Function Documentation":
>
>    The last line of the documentation string can specify calling
>    conventions different from the actual function arguments.  Write text
>   like this:
>
>      \(fn ARGLIST)

Ah, there it is! I was lazy and just checked the docstring of
defmacro, where I could see no mentioning of this.

Thanks!

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Eli Zaretskii]

> Date: Thu, 06 Jul 2006 22:44:03 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> 
> I think I can guess what the doc string for this function means, but it 
> would be more easy if SPEC where explicitly explained.

Where are you looking, and in what Emacs version?  The current doc
string for dotimes-with-progress-reporter (see below) mentions all its
arguments (SPEC isn't one of them), and it's been like that since
January 2005.

    dotimes-with-progress-reporter is a Lisp macro in `subr.el'.
    (dotimes-with-progress-reporter (var count [result]) message body...)

    Loop a certain number of times and report progress in the echo area.
    Evaluate body with var bound to successive integers running from
    0, inclusive, to count, exclusive.  Then evaluate result to get
    the return value (nil if result is omitted).

    At each iteration message followed by progress percentage is
    printed in the echo area.  After the loop is finished, message
    followed by word "done" is printed.  This macro is a
    convenience wrapper around `make-progress-reporter' and friends.

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Lennart Borgman]

Eli Zaretskii wrote:
>> Date: Thu, 06 Jul 2006 22:44:03 +0200
>> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
>>
>> I think I can guess what the doc string for this function means, but it 
>> would be more easy if SPEC where explicitly explained.
>>     
>
> Where are you looking, and in what Emacs version?  The current doc
> string for dotimes-with-progress-reporter (see below) mentions all its
> arguments (SPEC isn't one of them), and it's been like that since
> January 2005.
>   
I am sorry, I looked at the code but misunderstood what I saw. I have 
tried to clear this out in another message.

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Eli Zaretskii]

> Date: Fri, 07 Jul 2006 14:07:36 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC:  emacs-devel@gnu.org
> 
> I am sorry, I looked at the code but misunderstood what I saw. I have 
> tried to clear this out in another message.

I don't see any other messages on related subjects.

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Lennart Borgman]

Eli Zaretskii wrote:
>> Date: Fri, 07 Jul 2006 14:07:36 +0200
>> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
>> CC:  emacs-devel@gnu.org
>>
>> I am sorry, I looked at the code but misunderstood what I saw. I have 
>> tried to clear this out in another message.
>>     
>
> I don't see any other messages on related subjects.
>   
Please look in the archive. It seems like you have not got or seen these 
messages then for some reason.

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Eli Zaretskii]

> Date: Fri, 07 Jul 2006 17:34:04 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC:  emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> >> Date: Fri, 07 Jul 2006 14:07:36 +0200
> >> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> >> CC:  emacs-devel@gnu.org
> >>
> >> I am sorry, I looked at the code but misunderstood what I saw. I have 
> >> tried to clear this out in another message.
> >>     
> >
> > I don't see any other messages on related subjects.
> >   
> Please look in the archive. It seems like you have not got or seen these 
> messages then for some reason.

There's nothing in the archives, perhaps because the archives het
updated only once a day.

What was the Subject of that message, and when was it sent?

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Lennart Borgman]

Eli Zaretskii wrote:
> There's nothing in the archives, perhaps because the archives het
> updated only once a day.
>
> What was the Subject of that message, and when was it sent?
>   
See http://lists.gnu.org/archive/html/emacs-devel/2006-07/msg00324.html

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Richard Stallman]

    I think I can guess what the doc string for this function means, but it 
    would be more easy if SPEC where explicitly explained.

The doc string explains the parts of the call in meaningful terms.
SPEC is just for internal implementation purposes; users should
not see it.  What did you do to look at the doc string
which mentioned SPEC?

Re: dotimes-with-progress-reporter doc string lacks SPEC

[Lennart Borgman]

Richard Stallman wrote:
>     I think I can guess what the doc string for this function means, but it 
>     would be more easy if SPEC where explicitly explained.
>
> The doc string explains the parts of the call in meaningful terms.
> SPEC is just for internal implementation purposes; users should
> not see it.  What did you do to look at the doc string
> which mentioned SPEC?
>   
I looked at the sources. At least I learned something from this - I hope ;-)