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

From: Howard Melman <[email-masked]>
Date: Mon, 3 Feb 2020 14:31:43 -0500

On Jan 31, 2020, at 2:24 PM, Eli Zaretskii <[email-masked]> wrote:

> From: Howard Melman <[email-masked]>
>> 
>>> 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