unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* (declare (debug 0))
@ 2021-10-19  1:40 Stephen Gildea
  2021-10-19 12:29 ` Stefan Monnier
  0 siblings, 1 reply; 9+ messages in thread
From: Stephen Gildea @ 2021-10-19  1:40 UTC (permalink / raw)
  To: emacs-devel

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?



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-19  1:40 (declare (debug 0)) Stephen Gildea
@ 2021-10-19 12:29 ` Stefan Monnier
  2021-10-20  5:22   ` Stephen Gildea
  0 siblings, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2021-10-19 12:29 UTC (permalink / raw)
  To: Stephen Gildea; +Cc: emacs-devel

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-19 12:29 ` Stefan Monnier
@ 2021-10-20  5:22   ` Stephen Gildea
  2021-10-20 12:33     ` Stefan Monnier
  0 siblings, 1 reply; 9+ messages in thread
From: Stephen Gildea @ 2021-10-20  5:22 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-20  5:22   ` Stephen Gildea
@ 2021-10-20 12:33     ` Stefan Monnier
  2021-10-21  1:46       ` Stephen Gildea
  0 siblings, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2021-10-20 12:33 UTC (permalink / raw)
  To: Stephen Gildea; +Cc: emacs-devel

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




^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-20 12:33     ` Stefan Monnier
@ 2021-10-21  1:46       ` Stephen Gildea
  2021-10-21 16:44         ` Stefan Monnier
  0 siblings, 1 reply; 9+ messages in thread
From: Stephen Gildea @ 2021-10-21  1:46 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

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}



^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-21  1:46       ` Stephen Gildea
@ 2021-10-21 16:44         ` Stefan Monnier
  2021-10-21 17:10           ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2021-10-21 16:44 UTC (permalink / raw)
  To: Stephen Gildea; +Cc: emacs-devel

> 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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-21 16:44         ` Stefan Monnier
@ 2021-10-21 17:10           ` Eli Zaretskii
  2021-10-21 19:04             ` Stephen Gildea
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2021-10-21 17:10 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: stepheng+emacs, emacs-devel

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



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-21 17:10           ` Eli Zaretskii
@ 2021-10-21 19:04             ` Stephen Gildea
  2021-10-21 19:17               ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Stephen Gildea @ 2021-10-21 19:04 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Stefan Monnier, emacs-devel

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.



^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: (declare (debug 0))
  2021-10-21 19:04             ` Stephen Gildea
@ 2021-10-21 19:17               ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2021-10-21 19:17 UTC (permalink / raw)
  To: Stephen Gildea; +Cc: monnier, emacs-devel

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



^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-10-21 19:17 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-10-19  1:40 (declare (debug 0)) Stephen Gildea
2021-10-19 12:29 ` Stefan Monnier
2021-10-20  5:22   ` Stephen Gildea
2021-10-20 12:33     ` Stefan Monnier
2021-10-21  1:46       ` Stephen Gildea
2021-10-21 16:44         ` Stefan Monnier
2021-10-21 17:10           ` Eli Zaretskii
2021-10-21 19:04             ` Stephen Gildea
2021-10-21 19:17               ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).