bug#25106: 24.5; easy-menu doc strings

[Drew Adams <drew.adams@oracle.com>]

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