Update doc of Edebug specification for macros

doc/lispref/edebug.texi:  Update documentation of Edebug specification:
- Do not document "0" as a recommended shortcut for non-instrumented
arguments; nobody knows about nor uses this, so don't encourage it.
- Add an example equivalent to (declare (debug (&rest sexp))).
This commit is contained in:
Stephen Gildea 2021-10-21 20:10:53 -07:00
parent 5bc522b4f4
commit 9529e1d2fb

View file

@ -1216,9 +1216,7 @@ directs processing of arguments.
@table @asis
@item @code{t}
All arguments are instrumented for evaluation.
@item @code{0}
None of the arguments is instrumented.
This is short for @code{(body)}.
@item a symbol
The symbol must have an Edebug specification, which is used instead.
@ -1528,6 +1526,16 @@ example of the @code{let} specification.
It may be easier to understand Edebug specifications by studying
the examples provided here.
Consider a hypothetical macro @code{my-test-generator} that runs
tests on supplied lists of data. Although it is Edebug's default
behavior to not instrument arguments as code, as controlled by
@code{edebug-eval-macro-args} (@pxref{Instrumenting Macro Calls}),
it can be useful to explicitly document that the arguments are data:
@example
(def-edebug-spec my-test-generator (&rest sexp))
@end example
A @code{let} special form has a sequence of bindings and a body. Each
of the bindings is either a symbol or a sublist with a symbol and
optional expression. In the specification below, notice the @code{gate}