bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Say that
>>
>>   (apply-partially f arg_1 ... arg_n)
>>
>> is equivalent to
>>
>>   (lambda (&rest args) (apply f arg_1 ... arg_n args))
>
> Sorry, I don't see how this is an improvement.
>
> Accidentally, the current text is a bit different from what you cited:
>
>    -- Function: apply-partially func &rest args
>        This function returns a new function which, when called, will call
>        FUNC with the list of arguments composed from ARGS and additional
>        arguments specified at the time of the call.  If FUNC accepts N
>        arguments, then a call to `apply-partially' with `M < N' arguments
>        will produce a new function of `N - M' arguments.
>
>> And I think that the paragraph about `apply-partially` should be merged
>> into the later text talking about functionals, because the main use case
>> of `apply-partially` is to construct anonymous functions for usage as
>> argument to some other function.
>
> If you mean this:
>
>      It is common for Lisp functions to accept functions as arguments or
>   find them in data structures (especially in hook variables and property
>   lists) and call them using `funcall' or `apply'.  Functions that accept
>   function arguments are often called "functionals".
>
>      Sometimes, when you call a functional, it is useful to supply a no-op
>   function as the argument.  Here are two different kinds of no-op
>   function:
>
> then it directly follows the part we were talking about.

There was a discussion here about how to improve the 'apply-partially'
documentation, but it didn't yield any concrete suggestions for
improvements.  I read the text we have now, and I find it clear with
regards to the questions raised in this thread, so I'm closing this bug
report.

If this conclusion is incorrect and this is still an issue, please reply
to this email (use "Reply to all" in your email client) and we might
reconsider.  We are more likely to reconsider if such a request comes
with a concrete suggestion for how to improve this text, preferably in
the form of a patch.

Thanks.