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

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Fri, 23 May 2014 23:39:02 UTC

Severity: minor

Tags: wontfix

Found in version 24.4.50

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 17571 in the body.
You can then email your comments to 17571 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#17571; Package emacs. (Fri, 23 May 2014 23:39:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Fri, 23 May 2014 23:39:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.4.50; doc string of `advice-function-mapc' etc.
Date: Fri, 23 May 2014 16:38:15 -0700 (PDT)
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 <at> 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''




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#17571; Package emacs. (Wed, 14 Aug 2019 23:44:02 GMT) Full text and rfc822 format available.

Message #8 received at 17571 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 17571 <at> debbugs.gnu.org
Subject: Re: bug#17571: 24.4.50; doc string of `advice-function-mapc' etc.
Date: Wed, 14 Aug 2019 16:43:35 -0700
Drew Adams <drew.adams <at> 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




Added tag(s) wontfix. Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Wed, 14 Aug 2019 23:44:02 GMT) Full text and rfc822 format available.

bug closed, send any further explanations to 17571 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Wed, 14 Aug 2019 23:44:03 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#17571; Package emacs. (Thu, 15 Aug 2019 00:42:01 GMT) Full text and rfc822 format available.

Message #15 received at 17571 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 17571 <at> debbugs.gnu.org
Subject: RE: bug#17571: 24.4.50; doc string of `advice-function-mapc' etc.
Date: Wed, 14 Aug 2019 17:40:56 -0700 (PDT)
> > 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)))))




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Thu, 12 Sep 2019 11:24:06 GMT) Full text and rfc822 format available.

This bug report was last modified 4 years and 199 days ago.

Previous Next


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