master 9029212c86: * lisp/emacs-lisp/debug-early.el: Improve the documentation

[Alan Mackenzie]

branch: master
commit 9029212c869aa532e14d5e2048df070902d4ca8f
Author: Alan Mackenzie <acm@muc.de>
Commit: Alan Mackenzie <acm@muc.de>

    * lisp/emacs-lisp/debug-early.el: Improve the documentation
---
 lisp/emacs-lisp/debug-early.el | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/lisp/emacs-lisp/debug-early.el b/lisp/emacs-lisp/debug-early.el
index 718000bfa4..e557643e46 100644
--- a/lisp/emacs-lisp/debug-early.el
+++ b/lisp/emacs-lisp/debug-early.el
@@ -24,10 +24,12 @@
 
 ;;; Commentary:
 
-;; This file dumps a backtrace on stderr when an error is thrown.
-;; It has no dependencies on any Lisp libraries and is thus suitable
-;; for generating backtraces in the early parts of bootstrapping.  It
-;; is also good for generating backtraces in batch mode in general.
+;; This file dumps a backtrace on stderr when an error is thrown.  It
+;; has no dependencies on any Lisp libraries and is thus used for
+;; generating backtraces for bugs in the early parts of bootstrapping.
+;; It is also always used in batch model.  It was introduced in Emacs
+;; 29, before which there was no backtrace available during early
+;; bootstrap.
 
 (defalias 'debug-early-backtrace
   #'(lambda ()
@@ -60,14 +62,22 @@ of the build process."
 
 (defalias 'debug-early
   #'(lambda (&rest args)
-  "Print a trace of Lisp function calls currently active.
+  "Print an error message with a backtrace of active Lisp function calls.
 The output stream used is the value of `standard-output'.
 
-There should be two ARGS, the symbol `error' and a cons of
-the error symbol and its data.
+The Emacs core calls this function after an error has been
+signaled, and supplies two ARGS.  These are the symbol
+`error' (which is ignored) and a cons of the error symbol and the
+error data.
+
+`debug-early' is a simplified version of `debug', and is
+available during the early parts of the build process.  It is
+superseded by `debug' after enough Lisp has been loaded to
+support the latter, except in batch mode which always uses
+`debug-early'.
 
-This is a simplified version of `debug', intended for use
-in debugging the early parts of the build process."
+(In versions of Emacs prior to Emacs 29, no backtrace was
+available before `debug' was usable.)"
   (princ "\nError: ")
   (prin1 (car (car (cdr args))))       ; The error symbol.
   (princ " ")