bug#17871: 24.4.50; (elisp) `Core Advising Primitives': interactive spec as function?

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

> AFAIK using a function as interactive SPEC is only useful for functions
> used as advices, so there is nothing to cross-reference.  And the node
> explains well how it works.  What information is missing in your
> opinion?

The doc about interactive specs says nothing (that I have found)
about the possibility of the spec being a function.  On the contrary,
it says that it must be a string or a sexp whose evaluation returns
a list (of argument values).  That *excludes* a sexp that returns
a function.

Even if, as you say, using a functional SPEC has only the one
use case (advising), the doc about interactive specs should call
out both (a) the *possibility* of a functional SPEC and (b) the
fact that this *can only be used for advising*.

And yes, that updated doc about interactive specs should then
cross-reference the doc about using a functional interactive spec
for advising - and vice versa.

The doc that says what an interactive spec is and what forms it
can take (e.g. node `Defining Commands' and its children,
particularly `Using Interactive') currently excludes the
possibility of it being a function.  So it makes no sense for
some other (far removed) node to now talk casually of *using*
that possibility.  If you cannot define an interactive spec as a
function (as the doc indicates) then how can you use it as such?

This is the result of introducing a new feature without properly
documenting it.  Hopefully this will be corrected.

And that points to a second bug involved here: this new feature
(the possibility of a functional interactive spec) is not even
mentioned in NEWS.  The addition of `nadvice.el' is mentioned,
but not the change to what an interactive spec is and what
forms it can take.

Furthermore, there is nothing in NEWS about `defadvice' being
deprecated (or whatever its official limbo status is now).

Instead, there is an entry that mentions a new limitation on it:
"`defadvice' does not honor the `freeze' flag and cannot advise
special-forms any more."  And that suggests just the opposite
of its being deprecated.

(And FWIW, stripping the manual of its doc for `defadvice' was
quite unwise.)