[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#16959: 24.3.50; defadvice docstring out of date

From: Florian Beck
Subject: bug#16959: 24.3.50; defadvice docstring out of date
Date: Tue, 11 Mar 2014 06:37:17 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.3.0

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]