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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 39295 <at> debbugs.gnu.org
Subject: bug#39295: 26.3; kbd-help property is undocumented
Date: Fri, 31 Jan 2020 19:10:47 +0200

> 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.

> 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.

Previous Next

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