bug#25106: 24.5; easy-menu doc strings

bug#25106: 24.5; easy-menu doc strings

[Drew Adams]

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'

bug#25106: 24.5; easy-menu doc strings

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#25106: 24.5; easy-menu doc strings

[Drew Adams]

> > 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? ;-)

bug#25106: 24.5; easy-menu doc strings

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#25106: 24.5; easy-menu doc strings

[Drew Adams]

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

bug#25106: 24.5; easy-menu doc strings

[Eli Zaretskii]

> Date: Sun, 28 Jul 2019 09:40:59 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 25106@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.

bug#25106: 24.5; easy-menu doc strings

[Drew Adams]

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

bug#25106: 24.5; easy-menu doc strings

[Noam Postavsky]

Drew Adams <drew.adams@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.