RE: 1) (elisp) `Advising Named Functions', 2) search filtering example

[Drew Adams]

> > You're right. I did have the impression that add-function was
> > considered to be okay, just like add-hook is.
> 
> It is.
> 
> > the important distinction is between the thing being added to, not the
> > function used to do the adding.
> 
> That's right.  For `foo-predicate` and `foo-bar-function`, modifying the
> variable is the raison d'être of that variable, so it's not harmful:
> programmers know that by design this value may change.

But advising such a variable also advises its function value.

Applying macro `add-function' to `isearch-filter-predicate'
advises the value - the function itself.  It does not just
point the variable to a different value (function).  This is
a bit different from just saying that because the variable
has a function value users will expect the variable value
to be changeable.

To be clear, I don't think I have a problem with a policy
change that says that advising is now OK also for Emacs
itself.  But I think the policy should be recognized if this
is the case, and the doc should reflect it.
 
> On the contrary (symbol-function <foo>) is the value associated to
> a function name and programmers usually expect that function to be
> defined at somewhere in a file (in a single place) and the value is
> expected (by the programmer and by other chunks of code which call it)
> to be faithful to the file's code.

If you advise either `isearch-filter-predicate' (as a place)
or its value (e.g. `isearch-filter-visible') then
`(symbol-function isearch-filter-predicate)' returns an advice
(an object that satisfies "internal" predicate `advice--p').

The doc commands pretty much DTRT (but see bug #14734).  But
the function that is the value of an advised function variable
such as `isearch-filter-predicate' _is advised_, and its
`symbol-function' reflects that.

(In fact, to retrieve the name of the function that is
advised, you need to do some digging (e.g., use "internal" and
undocumented function `advice--cd*r').