From bd0c75897153ea5ce1e4ba12c81c3b280a0b95e4 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 22 Dec 2023 16:49:49 +0200
Subject: [PATCH] Improve documentation of new native-compilation commands

* lisp/progmodes/elisp-mode.el (emacs-lisp-mode-menu)
(emacs-lisp-native-compile, emacs-lisp-native-compile-and-load):
Doc fixes.

* doc/lispref/compile.texi (Native-Compilation Functions):
Document 'emacs-lisp-native-compile' and
'emacs-lisp-native-compile-and-load'.
---
 doc/lispref/compile.texi     | 15 +++++++++++++--
 lisp/progmodes/elisp-mode.el | 16 ++++++++++------
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 96d66445360..3a6a3733055 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -878,8 +878,7 @@ well.
    You can natively-compile either a single function or macro
 definition, or a whole file of Lisp code, with the
 @code{native-compile} function.  Natively-compiling a file will
-produce both the corresponding @file{.elc} file with byte code and the
-@file{.eln} file with native code.
+produce the @file{.eln} file with native code.
 
 @findex native-comp-limple-mode
 @vindex native-comp-verbose
@@ -971,6 +970,18 @@ compilation subprocesses in parallel, under the control of
 Variables}).
 @end defun
 
+@deffn Command emacs-lisp-native-compile
+This command compiles the file visited by the current buffer into
+native code, if the file was changed since the last time it was
+natively-compiled.
+@end deffn
+
+@deffn Command emacs-lisp-native-compile-and-load
+This command compiles the file visited by the current buffer into
+native code, like @code{emacs-lisp-native-compile}, but it also loads
+the native code when the compilation finishes.
+@end deffn
+
   The following function allows Lisp programs to test whether
 native-compilation is available at runtime.
 
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index 354d98c50dc..105b017c215 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -85,10 +85,10 @@ All commands in `lisp-mode-shared-map' are inherited by this map."
     ["Byte-recompile Directory..." byte-recompile-directory
      :help "Recompile every `.el' file in DIRECTORY that needs recompilation"]
     ["Native-compile This File" emacs-lisp-native-compile
-     :help "Compile the current file containing the current buffer to native code"
+     :help "Compile this buffer's file to native code"
      :active (native-comp-available-p)]
     ["Native-compile and Load" emacs-lisp-native-compile-and-load
-     :help "Compile the current file to native code, then load compiled native code"
+     :help "Compile this buffer's file to native code, then load compiled native code"
      :active (native-comp-available-p)]
     ["Disassemble Byte Compiled Object..." disassemble
      :help "Print disassembled code for OBJECT in a buffer"]
@@ -224,7 +224,9 @@ All commands in `lisp-mode-shared-map' are inherited by this map."
 (declare-function comp-write-bytecode-file "comp")
 
 (defun emacs-lisp-native-compile ()
-  "Native-compile synchronously the current file (if it has changed)."
+  "Native-compile the current buffer's file (if it has changed).
+This invokes a synchronous native-compilation of the file that is
+visited by the current buffer."
   (interactive nil emacs-lisp-mode)
   (emacs-lisp--before-compile-buffer)
   (let* ((byte+native-compile t)
@@ -234,12 +236,14 @@ All commands in `lisp-mode-shared-map' are inherited by this map."
       (comp-write-bytecode-file eln))))
 
 (defun emacs-lisp-native-compile-and-load ()
-  "Native-compile synchronously the current file (if it has changed).
-Load the compiled code when finished.
+  "Native-compile the current buffer's file (if it has changed), then load it.
+This invokes a synchronous native-compilation of the file that is
+visited by the current buffer, then loads the compiled native code
+when the compilation is finished.
 
 Use `emacs-lisp-byte-compile-and-load' in combination with
 `native-comp-jit-compilation' set to t to achieve asynchronous
-native compilation."
+native compilation of the current buffer's file."
   (interactive nil emacs-lisp-mode)
   (when-let ((byte-file (emacs-lisp-native-compile)))
     (load (file-name-sans-extension byte-file))))
-- 
2.39.2