bug#24540: 25.1; doc of `abbrev-expand-function(s)', "wrapper hooks",...

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 25 Sep 2016 07:53:30 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Let's check the doc, starting with `expand-abbrev':
> 
> "Calls `abbrev-expand-function' with no argument to do the work, and
> returns whatever it does."

Actually, it says this:

    "Expand the abbrev before point, if there is an abbrev there.
  Effective when explicitly called even when `abbrev-mode' is nil.
  Before doing anything else, runs `pre-abbrev-expand-hook'.
  Calls `abbrev-expand-function' with no argument to do the work,
  and returns whatever it does.  (This should be the abbrev symbol
  if expansion occurred, else nil.)"

IOW, it (1) describes what the command does, (2) mentions the function
it calls to do the actual work, and (3) explains what "whatever"
means.  Quite a lot less mysterious than what the single sentence you
presented might convey, IMO.

> (It should say that it calls the _value of variable_
> `abbrev-expand-function'.)

Yes, fixed.

> So we look at `abbrev-expand-function', which tells us that the default
> value is `abbrev--default-expand'.

Given the above description, I see no reason for looking at
abbrev-expand-function at all, as no information is missing.  But
let's play along nonetheless.

> (Why the default value of such a presumably user-modifiable variable
> should be considered an "internal" function is a mystery.)

Why not?  It's just a value, right?  The user-modifiable part is not
the value, it's the variable abbrev-expand-function, which is not
internal.

> So we look at `abbrev--default-expand', which tells us this:
> 
> "This respects the wrapper hook `abbrev-expand-functions'."

No, it tells this:

    "Default function to use for `abbrev-expand-function'.
  This respects the wrapper hook `abbrev-expand-functions'.
  Calls `abbrev-insert' to insert any expansion, and returns what it does."

So it mentions the (non-obsolete) variable abbrev-expand-function, and
only then tells you that it _also_ respects the obsolete hook
abbrev-expand-functions.  Again, quite a different picture.

(I fixed the doc string to say "also" and "obsolete" explicitly.)

> So the doc tells us about a "wrapper hook", which is presumably
> something like a hook, which is something that users can use.  But the
> wrapper hook we are pointed to is "obsolete", and we are told to instead
> use a different variable (sans "s") - which was the one we started with!

Not quite accurate, to say the least.  In particular, the non-obsolete
variable was mentioned _before_ the obsolete one in the first place.

> Now what about the mysterious term "wrapper hook", apparently introduced
> fairly recently?  Searching for it in the Emacs manual shows nothing.
> 
> Searching for it in the Elisp manual shows only mentions of particular
> "obsolete" wrapper hooks - no explanation of what is meant by a "wrapper
> hook".

It isn't documented in the manuals because it's an obsolete feature.
I added references to with-wrapper-hook to the few doc strings that
were referencing wrapper hooks (there were just 4 of them in all of
Emacs).

(The text of your report was repeated 3 times for some reason.)