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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: Drew Adams <drew.adams@HIDDEN>; dated Fri, 23 May 2014 23:39:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 23 May 2014 23:38:58 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri May 23 19:38:58 2014
Received: from localhost ([127.0.0.1]:58360 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Wnz3B-0001Iy-Tc
	for submit <at> debbugs.gnu.org; Fri, 23 May 2014 19:38:58 -0400
Received: from eggs.gnu.org ([208.118.235.92]:48066)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <drew.adams@HIDDEN>) id 1Wnz38-0001Ig-Pi
 for submit <at> debbugs.gnu.org; Fri, 23 May 2014 19:38:55 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1Wnz2s-0006J9-Vu
 for submit <at> debbugs.gnu.org; Fri, 23 May 2014 19:38:49 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_40 autolearn=disabled
 version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:51250)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1Wnz2s-0006J4-Sa
 for submit <at> debbugs.gnu.org; Fri, 23 May 2014 19:38:38 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:49735)
 by lists.gnu.org with esmtp (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1Wnz2j-0001F7-Vx
 for bug-gnu-emacs@HIDDEN; Fri, 23 May 2014 19:38:38 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1Wnz2Y-0006Hi-V5
 for bug-gnu-emacs@HIDDEN; Fri, 23 May 2014 19:38:29 -0400
Received: from aserp1040.oracle.com ([141.146.126.69]:45726)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <drew.adams@HIDDEN>) id 1Wnz2Y-0006Gm-Oy
 for bug-gnu-emacs@HIDDEN; Fri, 23 May 2014 19:38:18 -0400
Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94])
 by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id
 s4NNcGnn009800
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
 for <bug-gnu-emacs@HIDDEN>; Fri, 23 May 2014 23:38:17 GMT
Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85])
 by ucsinet22.oracle.com (8.14.5+Sun/8.14.5) with ESMTP id s4NNcG4k007455
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL)
 for <bug-gnu-emacs@HIDDEN>; Fri, 23 May 2014 23:38:16 GMT
Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9])
 by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s4NNcFA7028363
 for <bug-gnu-emacs@HIDDEN>; Fri, 23 May 2014 23:38:15 GMT
MIME-Version: 1.0
Message-ID: <97f7e8b0-09d0-4c04-a010-40696de16a97@default>
Date: Fri, 23 May 2014 16:38:15 -0700 (PDT)
From: Drew Adams <drew.adams@HIDDEN>
To: bug-gnu-emacs@HIDDEN
Subject: 24.4.50; doc string of `advice-function-mapc' etc.
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8  (707110) [OL
 12.0.6691.5000 (x86)]
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
X-Source-IP: ucsinet22.oracle.com [156.151.31.94]
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic]
X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address
 (bad octet value).
X-Received-From: 2001:4830:134:3::11
X-Spam-Score: -4.0 (----)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -4.0 (----)

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@HIDDEN
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=3D/c/Devel/emacs/snapshot/trunk
 --enable-checking=3Dyes,glyphs 'CFLAGS=3D-O0 -g3'
 LDFLAGS=3D-Lc:/Devel/emacs/lib 'CPPFLAGS=3D-DGC_MCHECK=3D1
 -Ic:/Devel/emacs/include''




Acknowledgement sent to Drew Adams <drew.adams@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#17571; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 31 Oct 2014 17:00:04 UTC

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