diff --git a/etc/DEBUG b/etc/DEBUG index 44f19900c64..dc1601a34f8 100644 --- a/etc/DEBUG +++ b/etc/DEBUG @@ -211,16 +211,19 @@ the debugger, but before running it, is the most efficient way of making sure control will be returned to the debugger when you need that. -There is a default function to give control to the debugger. It is -called debugger-trap. This is a do-nothing primitive, as a convenient -point to return control to the debugger. You can invoke interactively -with "M-x debugger-trap RET". The src/.gdbinit file in the Emacs source -distribution sets a breakpoint on this function. +The function 'debugger-trap' is a do-nothing interactive command that +exists to give control to the debugger. It is convenient to set a +breakpoint there to give control to the debugger when the function is +called. You can invoke it interactively with "M-x debugger-trap RET". +The src/.gdbinit file in the Emacs source distribution sets a breakpoint +in this function, so if you arrange for .gdbinit to be loaded, or load +it manually in a debugging session, the breakpoint is set for you +automatically. -'Fsignal' is a very useful place to put a breakpoint in. All Lisp +'Fsignal' is another very useful place to put a breakpoint in. All Lisp errors go through there. If you are only interested in errors that -would fire the Lisp debugger, breaking at 'maybe_call_debugger' is -useful. +would fire the Lisp debugger, breaking at 'maybe_call_debugger' is a +useful alternative. It is also useful to have a guaranteed way to return to the debugger at any arbitrary time. When using X, this is easy: type C-z at the diff --git a/src/eval.c b/src/eval.c index 829d6104618..0d4ae91136e 100644 --- a/src/eval.c +++ b/src/eval.c @@ -3092,14 +3092,14 @@ FUNCTIONP (Lisp_Object object) } DEFUN ("debugger-trap", Fdebugger_trap, Sdebugger_trap, 0, 0, "", - doc: /* Trap execution flow and hand over control to GDB. -The Emacs source file src/.gdbinit uses this via the GDB command -"break Fdebugger_trap". + doc: /* Stop Emacs and hand over control to GDB. +The Emacs source file src/.gdbinit sets a breakpoint in this function. -This function has no effect. It is reserved for debugging, and is not -called by Emacs otherwise. +This function does nothing. It is not called by Emacs otherwise, and +exists so that calling it or invoking it interactively will cause +GDB to kick in. -For Lisp debugging see debug, as well as edebug, in the manual: +For Lisp debugging see `debug', as well as `edebug', in the manual: "(elisp) Debugging". */) (void) {