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

From: Michael Heerdegen <[email-masked]>
Date: Sat, 23 Oct 2021 11:44:21 +0200

Stefan Kangas <[email-masked]> writes:

> 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.

I disagree.  The paragraph in the manual explains what the arity of the
function returned by `apply-partially' would be.

Directly following is an example suggesting that (apply-partially '+ 1)
is equivalent to #'1+ - which obviously contradicts that preceding
paragraph.

I'm a bit confused that you don't consider this a problem, and also that
you said there were no concrete suggestions.

There were concrete suggestions for improvements.  One was to simply
spell out the function that is constructed.  It is only one line, and
would make the semantics clear.

BTW, whenever I posted an example using `apply-partially', Stefan told
me that it would be more efficient to write out the lambda.  That aspect
could also be covered: when is worth using?

Or delete that paragraph, better to say nothing than to confuse readers.

Michael.