GNU bug report logs - #25106
24.5; easy-menu doc strings

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 25106 in the body.
You can then email your comments to 25106 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.5; easy-menu doc strings
Date: Sun, 4 Dec 2016 09:06:38 -0800 (PST)

Several doc strings functions refer to the form of the return value
of other functions, yet the doc strings of those other functions do
not even describe their return values.

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25106 <at> debbugs.gnu.org
Subject: Re: bug#25106: 24.5; easy-menu doc strings
Date: Sat, 27 Jul 2019 13:46:09 +0200

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

> Several doc strings functions refer to the form of the return value
> of other functions, yet the doc strings of those other functions do
> not even describe their return values.

What doc strings were you thinking of in particular?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 25106 <at> debbugs.gnu.org
Subject: RE: bug#25106: 24.5; easy-menu doc strings
Date: Sat, 27 Jul 2019 10:06:14 -0700 (PDT)

> > Several doc strings functions refer to the form of the return value
> > of other functions, yet the doc strings of those other functions do
> > not even describe their return values.
> 
> What doc strings were you thinking of in particular?

Dunno - that was 3 years ago.  Maybe take a look
at the easy-menu doc strings? ;-)

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25106 <at> debbugs.gnu.org
Subject: Re: bug#25106: 24.5; easy-menu doc strings
Date: Sun, 28 Jul 2019 11:55:56 +0200

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

>> > Several doc strings functions refer to the form of the return value
>> > of other functions, yet the doc strings of those other functions do
>> > not even describe their return values.
>> 
>> What doc strings were you thinking of in particular?
>
> Dunno - that was 3 years ago.  Maybe take a look
> at the easy-menu doc strings? ;-)

I skimmed a few, and nothing really jumped stood out.  Closing this bug
report; if somebody has a specific enhancement request in this area they
can open a new one.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 25106 <at> debbugs.gnu.org
Subject: RE: bug#25106: 24.5; easy-menu doc strings
Date: Sun, 28 Jul 2019 09:40:59 -0700 (PDT)

> > Dunno - that was 3 years ago.  Maybe take a look
> > at the easy-menu doc strings? ;-)
> 
> I skimmed a few, and nothing really jumped stood out.  Closing this bug
> report; if somebody has a specific enhancement request in this area
> they can open a new one.

OK, looking quickly at `easy-mmode.el':


1. Doc string of `easy-mmode-defmap' says it defines
   a constant whose value has the form of the return
   value of `easy-mmode-define-keymap'.  Doc string
   of `easy-mmode-define-keymap' does not specify the
   form of the keymap it returns.  (And keymaps can
   have very different kinds of entries.)

2. (Emacs 24.5, which is where the bug was filed, did
   the same thing for `define-minor-mode': referred
   to the form of what `easy-mmode-define-keymap'
   returns.  That's since been removed.)

Please have the doc string of `easy-mmode-define-keymap'
make clear just what the form of the keymap is that
it returns.  Easy-menu returns a specific kind of
keymap, and that's not clear from the doc.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25106 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#25106: 24.5; easy-menu doc strings
Date: Sun, 28 Jul 2019 20:01:16 +0300

> Date: Sun, 28 Jul 2019 09:40:59 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 25106 <at> debbugs.gnu.org
> 
> 1. Doc string of `easy-mmode-defmap' says it defines
>    a constant whose value has the form of the return
>    value of `easy-mmode-define-keymap'.

No, it says that the constant's value is the _result_ of
easy-mmode-define-keymap.  It says nothing about the form of the
keymap.  So there's no mystery to solve here.

Would you please learn to accept the judgment of the Emacs developers
regarding bug report?  All these futile "rearguard battles" are just
waste of everyone's time and energy.  Please always assume that your
arguments were considered in good faith, and the decision, if you
don't like it, was not meant to disregard your views in any way, it
just disagreed with you.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 25106 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: RE: bug#25106: 24.5; easy-menu doc strings
Date: Sun, 28 Jul 2019 11:04:24 -0700 (PDT)

> > 1. Doc string of `easy-mmode-defmap' says it defines
> >    a constant whose value has the form of the return
> >    value of `easy-mmode-define-keymap'.
> 
> No, it says that the constant's value is the _result_ of
> easy-mmode-define-keymap.

Correct.  Which implies that its form is the same.

The question raised by the report is how to know
what form the returned keymap has.

> It says nothing about the form of the keymap.

Exactly.  That's the problem reported.

It invites a reader, in effect, to go check the
doc of `easy-mmode-define-keymap'.  See if that
describes the form of the return value.

Going there, you find that there's no description
of it (beyond it being a keymap).  Your recourse
is to go to the code, even though easy-menu returns
a specific form of keymap, which its doc could
just as well specify.

If `easy-mmode-define-keymap' specified the form
of the keymap it returns then there would be no
difficulty.  It doesn't.  That's what this request
is about: help users by describing the particular
form of the keymap.

> So there's no mystery to solve here.

Mystery, no.  Suggested doc improvement, yes.

> Please always assume that your arguments were
> considered in good faith, and the decision, if
> you don't like it, was not meant to disregard
> your views in any way,

No, of course not.  No one said anything about
that.  I'm sure Lars acted in good faith - never
questioned that.

> it just disagreed with you.

Disagreement about whether the problem should be
addressed is normal - a judgment call.  People
judge things differently.  Nothing wrong with that.

It's a fact that the form of the keymap returned
isn't given in the doc string.  The enhancement
request suggests that it would help users if it
were.

I certainly understand that someone can decide
that a particular enhancement need not or should
not be made.

I replied to Lars's request to point out the doc
string(s) in question.  He looked for that and
didn't find it.

If that was the reason for closing (as he stated)
then pointing out the doc strings (as requested)
is appropriate, as is requesting that (given this
more specific information) the problem be fixed.

There could be other reasons to close the request.
I replied to the only reason given so far, saying
where the doc difficulty is.

Please consider adding the form of the returned
keymap to the doc string.  Just a request.

As for revisiting a closed report: maybe take a
look at #25195, which was also followed up on
after being closed as wont-fix.  The subsequent
discussion apparently caused Lars to change his
mind.

And no, nothing in that discussion put in question
Lars's good faith.  And yes, we're all appreciative
of the work Lars has been doing, revisiting old
bug reports.  I'm particularly grateful that many
of the problems I reported are now getting fixed.

Lars is moving quickly and carefully through many,
many bug reports, trying his best to quickly decide
their fate.  I don't think any of us has baked-in,
closed opinions - we're all open to new information
or new arguments pro & con.  This is a process.

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 25106 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, larsi <at> gnus.org
Subject: Re: bug#25106: 24.5; easy-menu doc strings
Date: Mon, 29 Jul 2019 10:51:11 -0400

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

> The question raised by the report is how to know
> what form the returned keymap has.
>
>> It says nothing about the form of the keymap.
>
> Exactly.  That's the problem reported.
>
>> So there's no mystery to solve here.

>> it just disagreed with you.
>
> Disagreement about whether the problem should be
> addressed is normal - a judgment call.  People
> judge things differently.  Nothing wrong with that.

From what I can tell, Lars just requested a clarification of the
original report which failed to specify what functions were being talked
about.  The disagreement is that Eli thinks specifying the particular
form of keymap being returned is not needed (Lars never said anything
about that either way).

By the way, I also think documenting the particular form of keymap
returned is not needed.

> As for revisiting a closed report: maybe take a
> look at #25195, which was also followed up on
> after being closed as wont-fix.  The subsequent
> discussion apparently caused Lars to change his
> mind.

I don't think Lars changed his mind about that exactly, he just misread
the original report.

Previous Next

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