bug#24663: 24.5; doc string of `completion-at-point-functions'

[Drew Adams <drew.adams@oracle.com>]

> > > I changed that to say "the entity at point" because the rest of the
> > > doc string refers to that.
> >
> > 1. It cannot be "THE" thing (or THE entity) at point.  Which one?
> 
> The one at point.

The symbol? word? file name? URL? ... (yes, ... - there are any
number of kinds of things, most of which - nay, all of which - 
could be completed.

> > You can get different kinds of thing at point.  You must provide
> > the desired THING type, for "thing at point" to mean anything.
> 
> My understanding is that it's up to the hooks.

Then them most that the doc can & should say is that SOMETHING
(some text) BEFORE point, is susceptible to completion.

> > 2. I don't see how/why saying "entity" changes anything, here.
> > "THE" entity?  What is that?
> 
> Then I guess I will say that I don't want to fix that part.

I got that.

> > 3. It is not text AT point that is completed.  It is text BEFORE
> > point that is completed.  AT can only refer to characters after
> > point, not before.
> 
> The doc string doesn't say "text", it says "entity".  IOW, it doesn't
> talk about characters.

What else is before point, besides characters?  What else gets
completed, besides text?

OK, presumably a face or other text or overlay property, or a marker,
before point could perhaps lead to some kind of completion.  What
that might amount to is anyone's guess.  I don't think non-text
completion is really what `completion-at-point-functions' is about
(or has been about).  It certainly isn't something that the doc
string should imagine.