bug#35250: Add simplest Advice example possible first

bug#35250: Add simplest Advice example possible first

[積丹尼 Dan Jacobson]

(info "(elisp) Advising Functions") starts out with a complicated
example.

        For example, in order to trace the calls to the process filter of a
     process PROC, you could use:

          (defun my-tracing-function (proc string)
            (message "Proc %S received %S" proc string))

          (add-function :before (process-filter PROC) #'my-tracing-function)

Please first add the simplest example possible:

Function A prints "a".

Make it print "ab" from now on.

bug#35250: Add simplest Advice example possible first

[Lars Ingebrigtsen]

積丹尼 Dan Jacobson <jidanni@jidanni.org> writes:

> (info "(elisp) Advising Functions") starts out with a complicated
> example.
>
>         For example, in order to trace the calls to the process filter of a
>      process PROC, you could use:
>
>           (defun my-tracing-function (proc string)
>             (message "Proc %S received %S" proc string))
>
>           (add-function :before (process-filter PROC) #'my-tracing-function)
>
> Please first add the simplest example possible:
>
> Function A prints "a".
>
> Make it print "ab" from now on.

I've never used nadvice before, and I have to say that I found that
section a bit confusing, too, because my immediate response was (like
Dan's) to say "well, it should be trivial to make an advice that just
modifies the output", so I thought "well, :around has to be it".

But it isn't, :around is the super-flexible one:

(defun my-foo (x)
  (* x 2))

(defun my-advice (old-fun x)
  (+ (funcall old-fun x) 1))

(advice-add 'my-foo :around #'my-advice)

(my-foo 3)
=> 7

Instead :filter-return is it, and it's the one mentioned last.  So I'm
adding this to the manual as an example first:

(defun my-double (x)
  (* x 2))

(defun my-increase (x)
  (+ x 1))

(advice-add 'my-double :filter-return #'my-increase)

(my-double 3)
7

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no