(declare (debug 0))

(declare (debug 0))

[Stephen Gildea]

The node Instrumenting Macro Calls in edebug.texi recommends declaring
  (debug 0)
to specify that none of the macro's arguments should be instrumented.
But all examples I could find in Emacs code use (debug nil) for this.

Which is it, 0 or nil?

If 0 is the preferred specification, should the documentation say what
other integers mean?

Re: (declare (debug 0))

[Stefan Monnier]

Stephen Gildea [2021-10-18 18:40:20] wrote:
> The node Instrumenting Macro Calls in edebug.texi recommends declaring
>   (debug 0)
> to specify that none of the macro's arguments should be instrumented.
> But all examples I could find in Emacs code use (debug nil) for this.
>
> Which is it, 0 or nil?
>
> If 0 is the preferred specification, should the documentation say what
> other integers mean?

As one of those rare souls who've been working on edebug.el recentishly,
I must say I hadn't noticed this and has no idea that 0 was supposed to
be treated specially.

I would have written (&rest sexp) instead, tho more likely I would have
written nothing at all and relies on the default behavior of Edebug to
not instrument args of macro calls.  This depends on
`edebug-eval-macro-args` being nil, but IMO this var should be removed
because setting it to non-nil will result in broken behavior in too
many situations.


        Stefan

Re: (declare (debug 0))

[Stephen Gildea]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>   I must say I [had] no idea that 0 was supposed to be treated specially.
>   
>   I would have written (&rest sexp) instead, tho more likely I would have
>   written nothing at all and relies on the default behavior of Edebug....

If even you didn't know about (debug 0), it sounds like I should update
the manual to recommend (debug nil) instead.

I do like the idea of offering (continuing to offer) a simple shorthand
that says "do not instrument args", even though that is the default and
is rarely used in current code.  Adding an explicit declaration saves
later readers/maintainers of a macro definition from having to figure
out whether a "debug" declaration is missing.

Re: (declare (debug 0))

[Stefan Monnier]

Stephen Gildea [2021-10-19 22:22:08] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>   I must say I [had] no idea that 0 was supposed to be treated specially.
>>   
>>   I would have written (&rest sexp) instead, tho more likely I would have
>>   written nothing at all and relies on the default behavior of Edebug....
>
> If even you didn't know about (debug 0), it sounds like I should update
> the manual to recommend (debug nil) instead.
>
> I do like the idea of offering (continuing to offer) a simple shorthand
> that says "do not instrument args", even though that is the default and
> is rarely used in current code.  Adding an explicit declaration saves
> later readers/maintainers of a macro definition from having to figure
> out whether a "debug" declaration is missing.

In my experience, macros whose args should not be instrumented are not
the most common, by far, and (&rest sexp) is sufficiently short and
clear for them.  I don't see any need to have something shorter.


        Stefan

Re: (declare (debug 0))

[Stephen Gildea]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>   In my experience, macros whose args should not be instrumented are not
>   the most common, by far, and (&rest sexp) is sufficiently short and
>   clear for them.  I don't see any need to have something shorter.

Then how about the following update to the documentation.  This
removes "0" as a recommended shortcut and instead adds a "not
instrumented" example.


diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 323130f237..7d67cc3af1 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1216,9 +1216,7 @@ Instrumenting Macro Calls
 @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 @@ Specification Examples
 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}

Re: (declare (debug 0))

[Stefan Monnier]

> Then how about the following update to the documentation.  This
> removes "0" as a recommended shortcut and instead adds a "not
> instrumented" example.

Looks good to me, thank you.
I think you can push it to `emacs-28` (tho it's not a bug fix, so you
might want to double check with Eli).


        Stefan

Re: (declare (debug 0))

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Thu, 21 Oct 2021 12:44:39 -0400
> 
> I think you can push it to `emacs-28` (tho it's not a bug fix, so you
> might want to double check with Eli).

Sorry, I'm no longer sure I understand what patch is being suggested
for the emacs-28 branch.

Re: (declare (debug 0))

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   > From: Stefan Monnier <monnier@iro.umontreal.ca>
>   > Cc: emacs-devel@gnu.org
>   > Date: Thu, 21 Oct 2021 12:44:39 -0400
>   > 
>   > I think you can push it to `emacs-28` (tho it's not a bug fix, so you
>   > might want to double check with Eli).
>   
>   Sorry, I'm no longer sure I understand what patch is being suggested
>   for the emacs-28 branch.

It's an update to edebug.texi.  My understanding is that documentation
changes are always welcome on the release branch.

Re: (declare (debug 0))

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> Date: Thu, 21 Oct 2021 12:04:54 -0700
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   > From: Stefan Monnier <monnier@iro.umontreal.ca>
> >   > Cc: emacs-devel@gnu.org
> >   > Date: Thu, 21 Oct 2021 12:44:39 -0400
> >   > 
> >   > I think you can push it to `emacs-28` (tho it's not a bug fix, so you
> >   > might want to double check with Eli).
> >   
> >   Sorry, I'm no longer sure I understand what patch is being suggested
> >   for the emacs-28 branch.
> 
> It's an update to edebug.texi.  My understanding is that documentation
> changes are always welcome on the release branch.

Yes, they are.