GNU bug report logs - #39295
26.3; kbd-help property is undocumented

Previous Next

Full log

Message #14 received at 39295 <at> debbugs.gnu.org (full text, mbox):

From: Howard Melman <hmelman <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39295 <at> debbugs.gnu.org
Subject: Re: 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 <at> gnu.org> wrote:
> 
>> From: Howard Melman <hmelman <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.