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