Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r108143: run-hooks-with-args-* do fixes (bug#12393)

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r108143: run-hooks-with-args-* do fixes (bug#12393)

[Stefan Monnier]

>  with the given arguments ARGS, until one of them
>  returns a non-nil value.  Then we return that value.
>  However, if they all return nil, we return nil.
> +If the value of HOOK is nil, this function returns nil.

That seems redundant, since if the hook is nil, all the functions on the
hook return nil.

> -the given arguments and its return value is returned.
> +the given arguments.  Then we return nil if the function returns nil,
> +and t if it returns non-nil.

Let's not force ourselves to return t.  IOW `non-nil' would be better.

>  If it is a list of functions, those functions are called, in order,
>  with the given arguments ARGS, until one of them returns nil.
> -Then we return nil.  However, if they all return non-nil, we return non-nil.
> +Then we return nil.  However, if they all return non-nil, we return t.
> +If the value of HOOK is nil, this function returns t.

Again here specifying t instead of `non-nil' is a bad idea.


        Stefan

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r108143: run-hooks-with-args-* do fixes (bug#12393)

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Tue, 18 Sep 2012 00:10:16 -0400
> Cc: emacs-devel@gnu.org
> 
> > -the given arguments and its return value is returned.
> > +the given arguments.  Then we return nil if the function returns nil,
> > +and t if it returns non-nil.
> 
> Let's not force ourselves to return t.  IOW `non-nil' would be better.

Also, a stylistic issue: we don't normally say "we return" in
documentation, since it's not clear who are "we" in this context.
Something like this would be better:

  The value returned is nil if the function returns nil, non-nil
  otherwise.

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r108143: run-hooks-with-args-* do fixes (bug#12393)

[Glenn Morris]

Stefan Monnier wrote:

>> +If the value of HOOK is nil, this function returns nil.
>
> That seems redundant, since if the hook is nil, all the functions on the
> hook return nil.

No harm in being explicit though? Since the rest of the doc begins "if
HOOK has a non-nil value..." and otherwise says nothing about HOOK == nil.

>> -the given arguments and its return value is returned.
>> +the given arguments.  Then we return nil if the function returns nil,
>> +and t if it returns non-nil.
>
> Let's not force ourselves to return t.  IOW `non-nil' would be better.

I thought about that, but wanted to make it clear that we do not return
the same non-nil value as the function. That was what the bug report was
about.

(Althought that is how it behaved until 24.1, when it was changed with
no annoucement and no doc update.)

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r108143: run-hooks-with-args-* do fixes (bug#12393)

[Glenn Morris]

Eli Zaretskii wrote:

> Also, a stylistic issue: we don't normally say "we return" in
> documentation, since it's not clear who are "we" in this context.
> Something like this would be better:
>
>   The value returned is nil if the function returns nil, non-nil
>   otherwise.

I was being consistent with the pre-existing doc of
run-hook-with-args-until-success and run-hook-with-args-until-failure,
which use that form (and the passive voice). I didn't feel like
correcting them both; but anyone else please feel free.

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24 r108143: run-hooks-with-args-* do fixes (bug#12393)

[Stefan Monnier]

>> That seems redundant, since if the hook is nil, all the functions on the
>> hook return nil.
> No harm in being explicit though?

No, no harm (other than being a bit verbose).
>>> -the given arguments and its return value is returned.
>>> +the given arguments.  Then we return nil if the function returns nil,
>>> +and t if it returns non-nil.
>> Let's not force ourselves to return t.  IOW `non-nil' would be better.
> I thought about that, but wanted to make it clear that we do not return
> the same non-nil value as the function.

Saying it returns `non-nil' is already very different from saying it
returns that function's value.

> (Althought that is how it behaved until 24.1, when it was changed with
> no annoucement and no doc update.)

And it might change again in the future, that's why I don't want to be
specific when there's no need to be.


        Stefan

RE: [Emacs-diffs] /srv/bzr/emacs/emacs-24r108143: run-hooks-with-args-* do fixes (bug#12393)

[Drew Adams]

>   The value returned is ...

Return ...

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24r108143: run-hooks-with-args-* do fixes (bug#12393)

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Tue, 18 Sep 2012 07:20:32 -0700
> 
> >   The value returned is ...
> 
> Return ...

Doesn't fit the style of the surrounding text, so it will confuse.

Re: [Emacs-diffs] /srv/bzr/emacs/emacs-24r108143: run-hooks-with-args-* do fixes (bug#12393)

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Drew Adams" <drew.adams@oracle.com>
>> Cc: <emacs-devel@gnu.org>
>> Date: Tue, 18 Sep 2012 07:20:32 -0700
>> 
>> >   The value returned is ...
>> 
>> Return ...
>
> Doesn't fit the style of the surrounding text, so it will confuse.

Then the surrounding text should be made to fit.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."