GNU bug report logs - #8638
24.0.50; Imenu should not include vacuous defvars

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 8638 in the body.
You can then email your comments to 8638 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 11:15:01 -0700

Could we please improve `lisp-imenu-generic-expression so that it does
not include vacuous defvars such as (defvar foobar), which are generally
used only to quiet the byte-compiler?

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-04-25 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

Message #8 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 20:50:37 +0200

On Sun, May 8, 2011 at 20:15, Drew Adams <drew.adams <at> oracle.com> wrote:

> Could we please improve `lisp-imenu-generic-expression so that it does
> not include vacuous defvars such as (defvar foobar), which are generally
> used only to quiet the byte-compiler?

With lexical binding, (defvar foobar) is used to tell the bytecompiler
that the variable has dynamic scope.

    Juanma

Message #11 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 12:07:31 -0700

> With lexical binding, (defvar foobar) is used to tell the bytecompiler
> that the variable has dynamic scope.

It's still a vacuous definition.  And any defvar tells the byte compiler that a
variable has dynamic scope, no?

This seems irrelevant to the bug report.  I'd still suggest removing vacuous
defvars from the menu.  Mixing in vacuous entries with entries that really
define variables distracts users.  You want to think that accessing a menu item
will take you to a real variable definition.

If someone wants to provide vacuous defvars in a different submenu from
`Variables' (e.g. `Vacuous Vars') I have no problem with that.  But I don't
really think that's needed.

FWIW, this is what I use in my code (imenu+.el):

(concat "^\\s-*("
        (regexp-opt
          '("defvar" "defconst" "defconstant" "defcustom"
            "defparameter" "define-symbol-macro") t)
        "\\s-+\\(\\sw\\(\\sw\\|\\s_\\)+\\)"
        "\\s-+[^) \t\n]")

Not perfect, perhaps, but it seems to do the job OK so far.

Message #14 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 21:25:29 +0200

> It's still a vacuous definition.  And any defvar tells the byte compiler that a
> variable has dynamic scope, no?

It also tells the user, so having them in the imenu doesn't seem
superfluous to me (I'm talking again of lexically-scoped packages).

    Juanma

Message #17 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 12:36:25 -0700

> > It's still a vacuous definition.  And any defvar tells the 
> > byte compiler that a variable has dynamic scope, no?
> 
> It also tells the user, so having them in the imenu doesn't seem
> superfluous to me (I'm talking again of lexically-scoped packages).

Submenu `Variables' should be for variable definitions, not vacuous defvars that
might be used to indicate something to the byte compiler.

As I said, if you want to also present those to the user, then let's put them in
a  separate submenu.  They amount to byte-compiler declarations.  Perhaps there
are other byte-compiler-related constructs that could also be added to the same
submenu.  Call it `Byte-Compiler' or `Declarations', perhaps.

But these are not variable definitions in the same sense as full defvars are.
Mixing them in with full definitions, in the same submenu, just amounts to
noise.  Separating them out in a separate menu would be fine.

Message #20 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 21:46:15 +0200

On Sun, May 8, 2011 at 21:36, Drew Adams <drew.adams <at> oracle.com> wrote:

> But these are not variable definitions in the same sense as full defvars are.

I disagree. IMHO, in a lexical binding package, yes, there are
variable definitions. In some cases the variables are documented in
the docstring of a function or somesuch, but they are real variables
nonetheless. Instead of sweeping them under the carpet, perhaps it
would be better to suggest the programmer to add proper docstrings and
initial values to them.

    Juanma

Message #23 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 21:46:38 +0200

> I disagree. IMHO, in a lexical binding package, yes, there are

s/there/they/

    Juanma

Message #26 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 13:03:10 -0700

> I disagree. IMHO, in a lexical binding package, yes, there are
> variable definitions. In some cases the variables are documented in
> the docstring of a function or somesuch, but they are real variables
> nonetheless. Instead of sweeping them under the carpet, perhaps it
> would be better to suggest the programmer to add proper docstrings and
> initial values to them.

No one is sweeping anything under the carpet.
If you want to show them in an Imenu menu, fine; just don't mix them in with
definitions that people will want to visit to see doc strings and initial
values.

That programmers should be encouraged to use doc strings and specify initial
values is a separate issue.  That does not imply that vacuous defvars should be
included in the Variables menu.

As a signal to the byte compiler, a vacuous definition is useful - as such.
That's what it is for.  By definition it should not have an initial value or doc
string.

That a vacuous definition, like a full one, is now used also to declare a
variable special (dynamic scoping) does not mean that vacuous defvars should be
included in the Variables menu.

Whether a vacuous definition should indicate dynamic scope to the byte-compiler
is another question.  As you say, in most cases what we want to suggest is that
programmers use a full definition for that, instead.  But using a vacuous
definition to quiet undefined var warnings is legitimate - in that case the
programmer does _not_ want to include any initial value.

IMO, you are mixing in things that don't belong to this thread.  A defvar that
is used _only_ as a byte-compiler declaration and not to provide an initial
value (and hopefully a doc string) does not belong in the same submenu as full
definitions.

When you follow a Variables menu entry to its code, you want to see what the
code for the variable is.  You do not want to see only a vacuous defvar that
provides no more information than the menu item itself.

Message #29 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 22:29:32 +0200

On Sun, May 8, 2011 at 22:03, Drew Adams <drew.adams <at> oracle.com> wrote:

> When you follow a Variables menu entry to its code, you want to see what the
> code for the variable is.  You do not want to see only a vacuous defvar that
> provides no more information than the menu item itself.

The imenu index is not documentation. It is an index to code. So if
the "vacuous variable" has twenty lines of comment explaining its
purpose and why it does not have or require a docstring or an initial
value, I fully expect imenu to help me get there too, just as if it
were a normal, "full" variable. Your expectations for imenu are just
that, your expectations. I prefer to be the judge of what it is
interesting in the code and what is not, not some imenu filter.

But that's just my opinion. I'm not going to complain if someone fixes
this bug to your liking.

    Juanma

Message #32 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 13:39:14 -0700

> > When you follow a Variables menu entry to its code, you 
> > want to see what the code for the variable is.  You do not
> > want to see only a vacuous defvar that
> > provides no more information than the menu item itself.
> 
> The imenu index is not documentation. It is an index to code. So if
> the "vacuous variable" has twenty lines of comment explaining its
> purpose and why it does not have or require a docstring or an initial
> value, I fully expect imenu to help me get there too, just as if it
> were a normal, "full" variable. Your expectations for imenu are just
> that, your expectations. I prefer to be the judge of what it is
> interesting in the code and what is not, not some imenu filter.
> 
> But that's just my opinion. I'm not going to complain if someone fixes
> this bug to your liking.

I understand.  How would you feel if Imenu included entries for defuns and
defvars that are commented out?  Wouldn't you want Imenu to judge that you are
not interested in those?

Certainly comments that include defuns and such could be important and
interesting to developers.  The question is what Imenu should include, and yes,
it is a judgment call based on expectations of what most users will want/expect.

Message #35 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 22:52:06 +0200

On Sun, May 8, 2011 at 22:39, Drew Adams <drew.adams <at> oracle.com> wrote:

> I understand.  How would you feel if Imenu included entries for defuns and
> defvars that are commented out?  Wouldn't you want Imenu to judge that you are
> not interested in those?

Well, we're not talking about commented out variables, so the
comparison isn't entirely fair.

But, to be honest, sometimes I think that entries for commented out
defuns and defvars would be useful... :-)

> Certainly comments that include defuns and such could be important and
> interesting to developers.  The question is what Imenu should include, and yes,
> it is a judgment call based on expectations of what most users will want/expect.

Not users. Developers. And developers are usually interested in a
package's variables. More so in a lexical-binding context, where the
fact that the defvar exists can (and does) alter semantics.

    Juanma

Message #38 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Juanma Barranquero'" <lekktu <at> gmail.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 8 May 2011 14:49:04 -0700

> > it is a judgment call based on expectations of what most 
> > users will want/expect.
> 
> Not users. Developers. And developers are usually interested in a
> package's variables. More so in a lexical-binding context, where the
> fact that the defvar exists can (and does) alter semantics.

Users includes users who develop, and more.  Imenu is for all Emacs users,
including developers.  And the question is not whether developers are interested
in a package's variables.  It is whether the Variables submenu should include
entries for vacuous defvars.

Message #41 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Juanma Barranquero <lekktu <at> gmail.com>
Cc: 8638 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Mon, 09 May 2011 11:19:34 -0300

>> Could we please improve `lisp-imenu-generic-expression so that it does
>> not include vacuous defvars such as (defvar foobar), which are generally
>> used only to quiet the byte-compiler?
> With lexical binding, (defvar foobar) is used to tell the bytecompiler
> that the variable has dynamic scope.

While it is true some some (defvar <foo>) are actually declarations that
<foo> is a locally-used dynamically bound variable (in which case,
maybe it could make sense to see it in imenu), the overwhelming
majority is to declare the existence of some variable in some other
package, in which case I don't think it deserves to be in imenu.
And even when it might make sense, its usefulness seems dubious since
those defvars don't hold much valuable info (like initial value,
docstring, or something).
So I'd tend to agree with Drew.  For completion purposes, we'd want to
pay attention to those defvars, but not for imenu.


        Stefan

Message #44 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 8638 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Mon, 9 May 2011 16:31:12 +0200

On Mon, May 9, 2011 at 16:19, Stefan Monnier <monnier <at> iro.umontreal.ca> wrote:

> So I'd tend to agree with Drew.  For completion purposes, we'd want to
> pay attention to those defvars, but not for imenu.

I had already conceded (Warnock style, interpretation #1 ;-)

    Juanma

Message #47 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <8638 <at> debbugs.gnu.org>
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Fri, 27 May 2011 09:00:13 -0700

> FWIW, this is what I use in my code (imenu+.el):
> (concat "^\\s-*("
>         (regexp-opt
>           '("defvar" "defconst" "defconstant" "defcustom"
>             "defparameter" "define-symbol-macro") t)
>         "\\s-+\\(\\sw\\(\\sw\\|\\s_\\)+\\)"
>         "\\s-+[^) \t\n]")
> Not perfect, perhaps, but it seems to do the job OK so far.


FWIW, I use this now.
Changed the whitespace match after var name.

(concat "^\\s-*("
        (regexp-opt
          '("defvar" "defconst" "defconstant" "defcustom"
            "defparameter" "define-symbol-macro") t)
        "\\s-+\\(\\sw\\(\\sw\\|\\s_\\)+\\)"
        "\\(\\s-\\|[\n]\\)+" ; \n has char syntax `>', not `-'
        "[^) \t\n]")

\s-+ does not match newlines in Lisp modes (newlines have comment-end syntax),
so I changed \s-+ to \(\s-\|[\n]\)+.  No doubt still not perfect, but seems to
work OK.

Message #50 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 05 Aug 2012 22:15:51 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> FWIW, I use this now.
> Changed the whitespace match after var name.

I committed a slightly different fix to trunk.  Thanks.

Message #55 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> gnu.org>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 5 Aug 2012 09:27:22 -0700

> > FWIW, I use this now.
> > Changed the whitespace match after var name.
> 
> I committed a slightly different fix to trunk.  Thanks.

OK, thanks.  But I wonder why you treated defvar differently from defconst,
defconstant, defcustom, defparameter, and define-symbol-macro here.  Shouldn't
the same thing apply to them?

Just wondering.  Not that their use of a vacuous definition would mean the same
thing, or even necessarily by correct syntax.  But shouldn't a vacuous
definition using one of those others also be ignored by Imenu?

Message #58 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8638 <at> debbugs.gnu.org
Subject: Re: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Mon, 06 Aug 2012 11:43:16 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> OK, thanks.  But I wonder why you treated defvar differently from
> defconst, defconstant, defcustom, defparameter, and
> define-symbol-macro here.  Shouldn't the same thing apply to them?

There is no such thing as (defconst foo), or (defcustom foo); the second
argument is non-optional.  So the reasoning which was used for defvar,
i.e. that a defvar with an omitted second arg is commonly used just to
silence the compiler, does not apply.

Message #61 received at 8638 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> gnu.org>
Cc: 8638 <at> debbugs.gnu.org
Subject: RE: bug#8638: 24.0.50; Imenu should not include vacuous defvars
Date: Sun, 5 Aug 2012 20:52:18 -0700

> > OK, thanks.  But I wonder why you treated defvar differently from
> > defconst, defconstant, defcustom, defparameter, and
> > define-symbol-macro here.  Shouldn't the same thing apply to them?
> 
> There is no such thing as (defconst foo), or (defcustom foo); 
> the second argument is non-optional.

Yes, I know.

> So the reasoning which was used for defvar, i.e. that a defvar
> with an omitted second arg is commonly used just to silence the
> compiler, does not apply.

But the reasoning that such things, if they ever occurred, would not represent
proper definitions, so Imenu should not index them, holds.  They would represent
incorrect syntax (i.e., errors), and should not be indexed.

Anyway, I'm OK with them being falsely indexed, and I would agree if you made
the argument that we do not try to prevent indexing of incorrect syntax in
general.
 

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.