bug#17571: 24.4.50; doc string of `advice-function-mapc' etc.

bug#17571: 24.4.50; doc string of `advice-function-mapc' etc.

[Drew Adams]

Not the only doc string in nadvice.el that needs help.  HTH.

 Apply F to every advice function in FUNCTION-DEF.
 F is called with two arguments: the function that was added, and the
 properties alist that was specified when it was added.

Could you please spend a few more words to try to help users understand
what this function does and what its parameters are/do?  Maybe this
could use a cross-reference to another doc string, to make things
clearer?

We can deduce from the verb "apply" that F must be a function.  OK, but
the Emacs convention is to give such a parameter a name like FUNCTION,
to make this clear (and to simplify the doc, BTW).  Why not do that?

FUNCTION-DEF is undefined.  All we know is that it somehow has "advice
functions" "in" it.  What an "advice function" is and what forms it can
take are not described here.  What "in" it means is unknown too.  (Is it
a list of functions perhaps)?  And why "-DEF", which usually stands for
"definition", "define", or "default" - what does it mean here?

F is called with two args.  The first is the "function that was added".
Huh?  What function is that?  Added to what?  When/how/where/why was it
added?

The second arg to F is "the properties alist that was specified when it
was added".  Huh?  Down one rabbit hole and into another.

All this doc string does for us is replace 3 unknowns: 2 parameters and
the function behavior, with many more unknowns and a headache.

What about the `mapc' in the function name?  Does that help?  Can you
perhaps describe the function in a way that relates to existing function
`mapc' - would that be helpful?  (If not, why bother to use `mapc' in
the name?)

The doc for other functions in nadvice.el is similarly confusing and
less helpful than it should be, when it is not missing altogether.

This library has apparently been around for 3 years now, and it has the
pretension of replacing the Emacs advice feature (`defadvice').  No
doubt it has something to offer in terms of functionality and ideas.
But at least docwise it doesn't seem ready for primetime yet.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-05-17 on ODIEONE
Bzr revision: 117119 eggert@cs.ucla.edu-20140517081131-ugu7ociaoec2xk7y
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#17571: 24.4.50; doc string of `advice-function-mapc' etc.

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Not the only doc string in nadvice.el that needs help.  HTH.
>
>  Apply F to every advice function in FUNCTION-DEF.
>  F is called with two arguments: the function that was added, and the
>  properties alist that was specified when it was added.

This seems to be a pretty internalish function deep down in the nadvice
library, and the doc string seems sufficient for such a function, I
think.  Perhaps it would have been better as a comment instead of a doc
string, really.

Closing.

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

bug#17571: 24.4.50; doc string of `advice-function-mapc' etc.

[Drew Adams]

> > Not the only doc string in nadvice.el that needs help.  HTH.
> >
> >  Apply F to every advice function in FUNCTION-DEF.
> >  F is called with two arguments: the function that
> >  was added, and the properties alist that was
> >  specified when it was added.
> 
> This seems to be a pretty internalish function deep down in the nadvice
> library, and the doc string seems sufficient for such a function, I
> think.  Perhaps it would have been better as a comment instead of a doc
> string, really.
> 
> Closing.

Unfortunate. I can't imagine why you'd think
such a thing.  This is hardly a function used
only to implement advice.  It's a utility
function.  And it's documented in the manual
(just as poorly, but it's there).

"Internalish"?  This function is about as
useful for advice as `mapcar' is for lists.
Nadvice deals with sequences of advice.  How
else would you map a function over them?

For example:

(remove-function
  isearch-filter-predicate
  (let ((oname  nil))
    (catch 'foo
      (advice-function-mapc
        (lambda (pred props)
          (when
            (equal predicate
                   (setq oname
                         (cdr (assq 'name
                                    props))))
            (throw 'foo oname)))
        isearch-filter-predicate)
      (setq predicate  (intern predicate)))))