GNU bug report logs - #16959
24.3.50; defadvice docstring out of date

Previous Next

Package: emacs;

Reported by: Florian Beck <fb <at> miszellen.de>

Date: Fri, 7 Mar 2014 15:19:01 UTC

Severity: minor

Found in version 24.3.50

Done: Stefan <monnier <at> iro.umontreal.ca>

Bug is archived. No further changes may be made.

Full log


View this message in rfc822 format

From: Florian Beck <fb <at> miszellen.de>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 16959 <at> debbugs.gnu.org
Subject: bug#16959: 24.3.50; defadvice docstring out of date
Date: Tue, 11 Mar 2014 06:37:17 +0100
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




This bug report was last modified 11 years and 56 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.