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''