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

[Howard Melman]

On Jan 31, 2020, at 2:24 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> From: Howard Melman <hmelman@gmail.com>
>> 
>>> 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. 
> 
> I see it explained in the doc string of help-at-pt-display-when-idle,
> and also in some other doc strings in help-at-pt.el.

I now see it in the :doc strings of that option. Specifically the lines: "The 
text printed from the `help-echo' property is often only relevant when using 
the mouse." and "The presence of a `kbd-help' property guarantees that non 
mouse specific help is available." That's all the information I wanted.

I still think if those were in the defcustom's docstring or a comment it would 
have been easier to find, but you're correct, it is in the code and if I had 
been more careful in reading all 13 occurrences I would have seen it.

>> The elisp manual section "Properties with Special Meanings" is incomplete 
>> without it.
> 
> It doesn't try to be complete.  Eventually, one needs to read the doc
> strings of the features one wants to use.

That's a fine stance to take, though I interpret the first paragraph of the 
"Properties with Special Meanings" section as saying it is attempting to be 
complete.

    Here is a table of text property names that have special built-in
    meanings.  The following sections list a few additional special property
    names that control filling and property inheritance.  All other names
    have no standard meaning, and you can use them as you like.

Howard