with-wrapper-hook

[Chong Yidong]

Two issues with the macro with-wrapper-hook, new in Emacs 24.1:

1. Shouldn't it be in NEWS (and the Lisp manual)?

2. The docstring needs work:

  (with-wrapper-hook VAR ARGS &rest BODY)

  Run BODY wrapped with the VAR hook.

  VAR is a special hook: its functions are called with a first argument
  which is the "original" code (the BODY), so the hook function can wrap
  the original function, or call it any number of times (including not
  calling it at all).  This is similar to an `around' advice.
  ...

The 1st argument passed to each function is said to be `the "original"
code (the BODY)'.  The word "code" is ambiguous---it's really a function
to be passed to `funcall', right?

The docstring is unclear about what happens in the case where there's
more than one function in the hook.  IIUC, stating that the argument is
`the BODY' is incorrect in that case; actually, the argument passed to
the Nth hook function is a recursively defined function, which if
funcalled would behave just as the with-wrapper-hook would if only the
(N+1) and subsequent hook functions were there.  Correct?