master 33222bd0000: Document apply-partially as inefficient

[Stefan Kangas]

branch: master
commit 33222bd000043ad79cf7d472fadf7cda6d49e31d
Author: Stefan Kangas <stefankangas@gmail.com>
Commit: Stefan Kangas <stefankangas@gmail.com>

    Document apply-partially as inefficient
    
    * doc/lispref/functions.texi (Calling Functions): Document that it is
    less inefficient than a regular 'lambda'.
    * lisp/subr.el (apply-partially): Adjust documentation like above and
    remove compiler macro.
    Ref: https://lists.gnu.org/r/emacs-devel/2025-03/msg00024.html
---
 doc/lispref/functions.texi | 12 +++++++++++-
 lisp/subr.el               | 13 +++++++------
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 024ff2b7d5a..99dfca217c2 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1055,7 +1055,17 @@ The result is a new function that accepts the rest of
 arguments and calls the original function with all the arguments
 combined.
 
-  Here's how to do partial application in Emacs Lisp:
+  In Emacs Lisp, this is best done with an anonymous function.  For
+example, if you have a function @samp{my-function} that takes two
+arguments, you could do something like this:
+
+@example
+(mapcar (lambda (x) (my-function 123 x)) @dots{})
+@end example
+
+  You can also do partial application using the function
+@code{apply-partially}.  However, this will be slower than using an
+anonymous function with @code{lambda}.
 
 @defun apply-partially func &rest args
 This function returns a new function which, when called, will call
diff --git a/lisp/subr.el b/lisp/subr.el
index 1647671d2b3..8f0366824d9 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -536,12 +536,13 @@ configuration."
 ARGS is a list of the first N arguments to pass to FUN.
 The result is a new function which does the same as FUN, except that
 the first N arguments are fixed at the values with which this function
-was called."
-  (declare (side-effect-free error-free)
-           (compiler-macro
-            (lambda (_)
-              `(lambda (&rest args2)
-                 ,`(apply ,fun ,@args args2)))))
+was called.
+
+In almost all cases, you want to use a regular anonymous function
+defined with `lambda' instead.  It will be faster, because it does not
+have the overhead of calling `apply' and `append', which this function
+has to do internally."
+  (declare (side-effect-free error-free))
   (lambda (&rest args2)
     (apply fun (append args args2))))