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: <monnier@iro.umontreal.ca>, <emacs-devel@gnu.org>
> Date: Mon, 28 May 2012 11:26:35 -0700
> 
> > And the names of the values are similarly non-specific.
> 
> The names do not stand alone without their descriptions.

I'm saying that the names don't help to understand the descriptions,
that's all.  If the descriptions were clear, I would care much less
for the names.  As things are, I'm grasping at every straw in sight.

>  Even so, I think that `yank' and `kill' are pretty clear even
> without reading their descriptions.

Not to me.  "For commands that do a yank" is not a description, it's
tautology at best.  "Ensures that the region about to be deleted is
not yanked"? why would it be yanked otherwise? and why the value is
'yank' if it "ensures the region will NOT be yanked"?  That just
doesn't make any sense!

'kill'? let's see... "`kill-region' is used on the selection, rather
than `delete-region'".  So? why would that matter, and when would I
want the former rather than the latter?  And what is "Text selected
with the mouse is typically yankable anyway" about? why "anyway"?

Etc., etc.  These are riddles, or maybe notes for someone who once
knew everything about this but forgot.  This is not documentation
suitable for first-time reading.  It leaves too much to previous
knowledge.

> I'm not saying the existing descriptions should not be changed.  I'm asking you
> what changes you have in mind.

How can I explain what I don't understand?  I _really_ have no clear
idea about what each value does, can you believe that?  If I'd study
the code long enough, I'd eventually understand, but I didn't.

> > What is needed is a clear description what each value does,
> 
> For instance?  What is missing, in your opinion?

I don't know.  How about if you try explaining each value in full,
from scratch?  Assume that only primitives like kill-region,
delete-region, 'yank', etc. are known, all the rest is not.  Explain
the effect of each value, both on the text that was selected and on
any other text that's involved.  Give at least one example for a use
case where each value will be useful.  That kind of stuff.