From: Stephen Gildea <stepheng+emacs@gildea.com>
Date: Fri, 22 Oct 2021 03:10:53 +0000 (-0700)
Subject: Update doc of Edebug specification for macros
X-Git-Tag: emacs-28.0.90~221
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=9529e1d2fb;p=emacs.git

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))).
---

diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 323130f2378..7d67cc3af11 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -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}