Improve documentation of Profiling features

* doc/lispref/debugging.texi (Profiling): Improve the description
of elp.el.  Improve wording of the rest of the section.  (Bug#30491)

* lisp/emacs-lisp/elp.el (elp-instrument-list): Make the
interactive invocation work.  Doc fix.

3 files changed, 41 insertions, 26 deletions

diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index bb022e4516a..c08a382ef12 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -922,48 +922,61 @@ be cleaner to combine them.
 @cindex measuring resource usage
 @cindex memory usage
 
-If your program is working correctly, but you want to make it run more
-quickly or efficiently, the first thing to do is @dfn{profile} your
-code so that you know how it is using resources.  If you find that one
-particular function is responsible for a significant portion of the
-runtime, you can start looking for ways to optimize that piece.
+If your program is working correctly, but not fast enough, and you
+want to make it run more quickly or efficiently, the first thing to do
+is @dfn{profile} your code so that you know where it spends most of
+the execution time.  If you find that one particular function is
+responsible for a significant portion of the execution time, you can
+start looking for ways to optimize that piece.
 
 Emacs has built-in support for this.  To begin profiling, type
 @kbd{M-x profiler-start}.  You can choose to profile by processor
-usage, memory usage, or both.  After doing some work, type
-@kbd{M-x profiler-report} to display a summary buffer for each
-resource that you chose to profile.  The names of the report buffers
-include the times at which the reports were generated, so you can
-generate another report later on without erasing previous results.
-When you have finished profiling, type @kbd{M-x profiler-stop} (there
-is a small overhead associated with profiling).
+usage, memory usage, or both.  Then run the code you'd like to speed
+up.  After that, type @kbd{M-x profiler-report} to display a summary
+buffer for each resource (cpu and memory) that you chose to profile.
+The names of the report buffers include the times at which the reports
+were generated, so you can generate another report later on without
+erasing previous results.  When you have finished profiling, type
+@kbd{M-x profiler-stop} (there is a small overhead associated with
+profiling, so we don't recommend leaving it active except when you are
+actually running the code you want to examine).
 
 The profiler report buffer shows, on each line, a function that was
-called, followed by how much resource (processor or memory) it used in
-absolute and percentage times since profiling started.  If a given
+called, followed by how much resources (cpu or memory) it used in
+absolute and percentage terms since profiling started.  If a given
 line has a @samp{+} symbol at the left-hand side, you can expand that
 line by typing @kbd{@key{RET}}, in order to see the function(s) called
 by the higher-level function.  Use a prefix argument (@kbd{C-u
 @key{RET}}) to see the whole call tree below a function.  Pressing
 @kbd{@key{RET}} again will collapse back to the original state.
 
-Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function.
-Press @kbd{d} to view a function's documentation.
-You can save a profile to a file using @kbd{C-x C-w}.
-You can compare two profiles using @kbd{=}.
+Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function
+at point.  Press @kbd{d} to view a function's documentation.  You can
+save a profile to a file using @kbd{C-x C-w}.  You can compare two
+profiles using @kbd{=}.
 
 @c FIXME reversed calltree?
 
 @cindex @file{elp.el}
 @cindex timing programs
-The @file{elp} library offers an alternative approach.  See the file
-@file{elp.el} for instructions.
+The @file{elp} library offers an alternative approach, which is useful
+when you know in advance which Lisp function(s) you want to profile.
+Using that library, you begin by setting @code{elp-function-list} to
+the list of function symbols---those are the functions you want to
+profile.  Then type @w{@kbd{M-x elp-instrument-list @key{RET} nil
+@key{RET}}} to arrange for profiling those functions.  After running
+the code you want to profile, invoke @w{@kbd{M-x elp-results}} to
+display the current results.  See the file @file{elp.el} for more
+detailed instructions.  This approach is limited to profiling
+functions written in Lisp, it cannot profile Emacs primitives.
 
 @cindex @file{benchmark.el}
 @cindex benchmarking
-You can check the speed of individual Emacs Lisp forms using the
-@file{benchmark} library.  See the functions @code{benchmark-run} and
-@code{benchmark-run-compiled} in @file{benchmark.el}.
+You can measure the time it takes to evaluate individual Emacs Lisp
+forms using the @file{benchmark} library.  See the macros
+@code{benchmark-run} and @code{benchmark-run-compiled} in
+@file{benchmark.el}.  You can also use the @code{benchmark} command
+for timing forms interactively.
 
 @c Not worth putting in the printed manual.
 @ifnottex
diff --git a/lisp/emacs-lisp/benchmark.el b/lisp/emacs-lisp/benchmark.el
index 589e76eaec0..d74446c7479 100644
--- a/lisp/emacs-lisp/benchmark.el
+++ b/lisp/emacs-lisp/benchmark.el
@@ -98,7 +98,8 @@ result.  The overhead of the `lambda's is accounted for."
 ;;;###autoload
 (defun benchmark (repetitions form)
   "Print the time taken for REPETITIONS executions of FORM.
-Interactively, REPETITIONS is taken from the prefix arg.
+Interactively, REPETITIONS is taken from the prefix arg, and
+the command prompts for the form to benchmark.
 For non-interactive use see also `benchmark-run' and
 `benchmark-run-compiled'."
   (interactive "p\nxForm: ")
diff --git a/lisp/emacs-lisp/elp.el b/lisp/emacs-lisp/elp.el
index dab17fd75b6..954e7aa73ae 100644
--- a/lisp/emacs-lisp/elp.el
+++ b/lisp/emacs-lisp/elp.el
@@ -278,8 +278,9 @@ Argument FUNSYM is the symbol of a defined function."
 (defun elp-instrument-list (&optional list)
   "Instrument, for profiling, all functions in `elp-function-list'.
 Use optional LIST if provided instead.
-If called interactively, read LIST using the minibuffer."
-  (interactive "PList of functions to instrument: ") ;FIXME: Doesn't work?!
+If called interactively, prompt for LIST in the minibuffer;
+type \"nil\" to use `elp-function-list'."
+  (interactive "xList of functions to instrument: ")
   (unless (listp list)
     (signal 'wrong-type-argument (list 'listp list)))
   (mapcar #'elp-instrument-function (or list elp-function-list)))