[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/bulk-tracing 32d26d7411 3/4: fixup! WIP: Add a 'tracing' section
From: |
Phil Sainty |
Subject: |
scratch/bulk-tracing 32d26d7411 3/4: fixup! WIP: Add a 'tracing' section to the elisp manual debugging node |
Date: |
Tue, 9 Aug 2022 10:15:46 -0400 (EDT) |
branch: scratch/bulk-tracing
commit 32d26d741163354d39795b300f3d893c0ae60545
Author: Phil Sainty <psainty@orcon.net.nz>
Commit: Phil Sainty <psainty@orcon.net.nz>
fixup! WIP: Add a 'tracing' section to the elisp manual debugging node
---
doc/lispref/debugging.texi | 50 ++++++++++++++++++++++++----------------------
1 file changed, 26 insertions(+), 24 deletions(-)
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 7c2ddbddc7..81a68490be 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -61,6 +61,7 @@ function (@pxref{Terminal Output}).
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Profiling:: Measuring the resources that your code uses.
+* Tracing:: Log function calls, arguments, and return values.
@end menu
@node Debugger
@@ -1088,14 +1089,16 @@ provided by the @file{trace.el} package. Many
functions may be traced
at the same time. The functions @code{trace-function-foreground} and
@code{trace-function-background} add a new trace to a single specified
function. The functions @code{trace-package}, @code{trace-regexp},
-and @code{trace-library} enable traces to be added to multiple
-functions in bulk. Calls to traced functions, including the values
-of their arguments, are logged to the @file{*trace-output*} buffer
-(or another buffer as specified).
+and @code{trace-library} enable traces to be added to functions en
+masse. Calls to traced functions, including the values of their
+arguments and return values, are logged to the @file{*trace-output*}
+buffer (or another buffer as specified).
-In addition, you can call @code{trace-values} in your code to output
-the values of its arguments to the trace buffer, to provide more trace
-information than is provided by the function calls alone.
+Optional 'context' expressions will be evaluated and logged both when
+the associated function is called and when it returns; and finally you
+may add explicit calls to @code{trace-values} to your code to log
+arbitrary other values to the trace buffer, if you wish to provide
+more data than is provided by function traces alone.
@deffn Command trace-function-foreground function &optional buffer context
This function adds a foreground trace to @var{function}. When called
@@ -1119,13 +1122,13 @@ stuff - use `trace-function-background' instead.
Calling `trace-function-foreground' again for the same FUNCTION will
update the optional argument behaviours to respect the new values.
-@end defun
+@end deffn
@deffn Command trace-function-background function &optional buffer context
This function adds a background trace to @var{function}. This is like
@code{trace-function-foreground}, but without popping up the output
buffer or changing the window configuration.
-@end defun
+@end deffn
@deffn Command trace-package prefix &optional buffer context after-load
This function calls @code{trace-function-background} for all functions
@@ -1141,7 +1144,7 @@ file. See `trace-function-foreground' for details of
@var{buffer} and
Calling `trace-package' again for the same @var{prefix} will update
the optional argument behaviours to respect the new values.
-@end defun
+@end deffn
@deffn Command trace-regexp regexp &optional buffer context after-load
This function calls @code{trace-function-background} for all functions
@@ -1161,11 +1164,11 @@ file. See `trace-function-foreground' for details of
@var{buffer} and
Calling `trace-regexp' again for the same @var{regexp} will update the
optional argument behaviours to respect the new values.
-@end defun
+@end deffn
@deffn Command trace-library library &optional buffer context after-load
This function calls @code{trace-function-background} for all functions
-defined in @var{library}.
+currently defined in @var{library} according to the @var{load-history}.
For any autoload declarations with a file name matching @var{library},
the associated function will be traced if and when it is defined.
@@ -1180,48 +1183,47 @@ AFTER-LOAD is non-nil then re-process @var{library}
after loading it
Calling `trace-library' again for the same @var{library} will update
the optional argument behaviours to respect the new values.
-@end defun
+@end deffn
@deffn Command trace-currently-traced &optional display-message
This function returns the list of currently traced function symbols.
When called interactively, or if @var{display-message} is non-nil, it
displays the list as a message.
-@end defun
+@end deffn
@deffn Command untrace-function function
-This function removes the trace on @var{function}. When called
-interactively, it prompts for @var{function} in the minibuffer.
-Calling @code{untrace-function} has no effect if @var{function} is not
-currently traced.
-@end defun
+This function removes the trace on @var{function}. This has no effect
+if @var{function} was not being traced. When called interactively, it
+prompts for @var{function} in the minibuffer.
+@end deffn
@deffn Command untrace-package prefix
This function calls @code{untrace-function} for all functions with
names starting with @var{prefix}. When called interactively, it
prompts for @var{prefix} in the minibuffer.
-@end defun
+@end deffn
@deffn Command untrace-regexp regexp
This function calls @code{untrace-function} for all functions matching
@var{regexp}. When called interactively, it prompts for @var{regexp}
in the minibuffer.
-@end defun
+@end deffn
@deffn Command untrace-library library
This function calls @code{untrace-function} for all functions defined
in @var{library}. When called interactively, it prompts for
@var{library} in the minibuffer.
-@end defun
+@end deffn
@deffn Command untrace-all
This function calls @code{untrace-function} for all functions.
-@end defun
+@end deffn
@deffn Function trace-values &rest values
This function inserts a message showing @var{values} into the trace
buffer. You can add explicit calls to @code{trace-values} into your
functions in order to provide additional tracing information.
-@end defun
+@end deffn
@defvar Variable inhibit-trace
If non-nil, all tracing is inhibited.