bug#39295: 26.3; kbd-help property is undocumented

[Howard Melman]

> On Jan 31, 2020, at 12:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Howard Melman <hmelman@gmail.com>
>> Date: Fri, 31 Jan 2020 11:10:26 -0500
> 
> [Please keep the bug address on the CC list.]
> 
>>> It indeed is unused, so I'm not sure it should be documented at this
>>> time.  As for "new": the help-at-pt.el file was added to Emacs 17
>>> years ago, and its original version already included support for this
>>> property.
>> 
>> Perhaps it should be deprecated? Without documentation it's unlikely to be 
>> used.
> 
> It is documented in the doc strings, isn't it?
> 
>> It would be nice if some place described it as unused (and perhaps as unused 
>> for a very long time). 
> 
> Unused in Emacs itself doesn't mean no one out there uses it.  A
> feature that is unused doesn't do any harm.

Well, just a little complexity. I've now forgotten what I was tracking down 
that led me to this code but it was an additional property I had to figure out 
if it was relevant to what I was looking for.

>> Since the code will use it, it should remain in the docstring. If you don't 
>> want to add it to the manual then may I suggest at a least a comment in the 
>> code saying so and what its intent was, perhaps in the package commentary, 
>> would be useful.
> 
> Not every feature is documented in the manual, only the important ones
> are.  And I'm not sure I see the utility of stating in comments that
> we don't document this in the manual: we don't say that about all the
> other features not mentioned in the manual.

I think some place should describe when code should use kbd-help as opposed to 
help-echo. 

The elisp manual section "Properties with Special Meanings" is incomplete 
without it. If it doesn't deserve a description there, then I do think a 
comment differentiating it from help-echo (even to say it's rarely used) would 
help.

Howard