bug#16959: 24.3.50; defadvice docstring out of date

[Florian Beck <fb@miszellen.de>]

On 10.03.2014 19:16, Glenn Morris wrote:

> Why do you think it is obsolete?

Because every hint of its existence has been expunged from the 
documentation and the new advice seems to offer the same functionality.

>> BTW, the nadvice info could use some more examples and a note on how
>> to transition from defadvice.
>
> I'll leave this report open till someone does that.

Some specifics:

  - See the documentation of the old advice: it starts with "altering 
the behavior of an existing function" (yeah! that's what I'm here for), 
then gives a simple example, a use case ("Suppose you wanted ...").

  - In contrast, the beginning of the new "Advising Functions" is a bit 
confusing: appropriate setter function? set-process-filter? What are 
"such hooks"?

  - The difference between add-function and advice-add is not entirely 
clear to me: the latter is for the "function cell of a symbol", a "named 
function and macros", "macros and autoloaded functions". Which is it? I 
can write

(add-function :after (symbol-function 'somefun) 'someadvice)

but should I? I have the feeling I should stick with advice-add unless 
dealing with process filters.

  - Indeed, it seems the documentation is in the wrong order: from a 
user's perspective, advice-add is what she usually wants and 
add-function is a special case.

  - The docstring of advice-add is useless: it should give me the info I 
need when writing an advice, which is in add-function. IMO is should be 
the other way around: the fact that you need advice-add for macros, etc 
should be mentioned in the docstring of add-function.

  - The page title "Advising Primitives" is misleading in the context of 
"Advising Functions" and "Advising Named Functions".

  - Interactive functions are only discussed in the docstring of 
add-function.

  - Add some examples that show how arguments work for someone who is 
not familiar with &rest and apply.

  - How about reimplementing the two examples from the old docu ("A 
Simple Advice Example" and "Around Advice")? That would also demonstrate 
how to transition to the new mechanism.


-- 
Florian Beck