Re: use and doc of function symbol properties [was: bug#11381: 23.3; isearch-search-and-update issue?]

[Eli Zaretskii <eliz@gnu.org>]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <11381@debbugs.gnu.org>, <emacs-devel@gnu.org>
> Date: Mon, 28 May 2012 10:34:34 -0700
> 
> The question you (Eli) raise is not specific to isearch or to
> delsel.

It was relevant to proliferation of the technique discussed there.

> But the use of symbol properties, including for function symbols, is nothing
> special.  It is similar to using attributes or methods with objects in OOP.
> What's sometimes missing perhaps is better documentation/discoverability.

That's what I was trying to say.  "Discoverability" means that someone
who calls a function from Org mode (say) that invokes some magic via
delsel should be able to understand how that magic happened.  I don't
see how this can be done today without a lot of digging.  If you are
hard-pressed for time, this could be a maintenance nightmare.

> Can you be more specific about what is missing from the Commentary in delsel.el?

It basically doesn't explain anything apart of the fact that the
property can have several values.  The exact effect of each value is
left unclear to the degree of obfuscation.  And the names of the
values are similarly non-specific.

What is needed is a clear description what each value does, and it
should be part of the doc string.  Right now, this info is only
available by reading the code.