[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#39295: 26.3; kbd-help property is undocumented
From: |
Howard Melman |
Subject: |
bug#39295: 26.3; kbd-help property is undocumented |
Date: |
Fri, 31 Jan 2020 12:23:45 -0500 |
> 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