GNU bug report logs - #13993
24.3.50; doc of `complete-with-action'

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 Mon, 18 Mar 2013 21:30: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; 18 Mar 2013 21:29:08 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 18 17:29:08 2013
Received: from localhost ([127.0.0.1]:34170 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1UHhcC-0008IL-5j
	for submit <at> debbugs.gnu.org; Mon, 18 Mar 2013 17:29:08 -0400
Received: from eggs.gnu.org ([208.118.235.92]:43007)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <drew.adams@HIDDEN>) id 1UHhcA-0008IE-1g
	for submit <at> debbugs.gnu.org; Mon, 18 Mar 2013 17:29:07 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1UHhaa-0005xU-Us
	for submit <at> debbugs.gnu.org; Mon, 18 Mar 2013 17:27:29 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-106.7 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED,
	RP_MATCHES_RCVD, UNPARSEABLE_RELAY,
	USER_IN_WHITELIST autolearn=unavailable version=3.3.2
Received: from lists.gnu.org ([208.118.235.17]:36524)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1UHhaa-0005xP-Rl
	for submit <at> debbugs.gnu.org; Mon, 18 Mar 2013 17:27:28 -0400
Received: from eggs.gnu.org ([208.118.235.92]:54343)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1UHhaW-0005ch-Q8
	for bug-gnu-emacs@HIDDEN; Mon, 18 Mar 2013 17:27:28 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1UHhaV-0005wM-Fz
	for bug-gnu-emacs@HIDDEN; Mon, 18 Mar 2013 17:27:24 -0400
Received: from aserp1040.oracle.com ([141.146.126.69]:45389)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <drew.adams@HIDDEN>) id 1UHhaV-0005w4-AP
	for bug-gnu-emacs@HIDDEN; Mon, 18 Mar 2013 17:27:23 -0400
Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93])
	by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with
	ESMTP id r2ILRKjK002546
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
	for <bug-gnu-emacs@HIDDEN>; Mon, 18 Mar 2013 21:27:21 GMT
Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157])
	by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	r2ILRJVG003074
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO)
	for <bug-gnu-emacs@HIDDEN>; Mon, 18 Mar 2013 21:27:20 GMT
Received: from abhmt105.oracle.com (abhmt105.oracle.com [141.146.116.57])
	by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id
	r2ILRJ38020795
	for <bug-gnu-emacs@HIDDEN>; Mon, 18 Mar 2013 16:27:19 -0500
Received: from dradamslap1 (/130.35.178.8)
	by default (Oracle Beehive Gateway v4.0)
	with ESMTP ; Mon, 18 Mar 2013 14:27:19 -0700
From: "Drew Adams" <drew.adams@HIDDEN>
To: <bug-gnu-emacs@HIDDEN>
Subject: 24.3.50; doc of `complete-with-action'
Date: Mon, 18 Mar 2013 14:27:17 -0700
Message-ID: <E60C8FBBA3774A2DAB950D77EE7929D4@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="US-ASCII"
Content-Transfer-Encoding: 7bit
X-Mailer: Microsoft Office Outlook 11
Thread-Index: Ac4kH11Da+eLtcU9TiyC71I/NyTMkQ==
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157
X-Source-IP: ucsinet21.oracle.com [156.151.31.93]
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: GNU/Linux 2.6.x
X-Received-From: 208.118.235.17
X-Spam-Score: -3.5 (---)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.13
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>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -6.2 (------)

The Emacs completion code and user completion code now use this
workhorse function everywhere, but its doc is woefully inadequate.
 
This function is not even mentioned in any manual.  And this is all that
the doc string says it does: "Perform completion ACTION."
 
What does that mean?  Well we find further on that "ACTION can be one of
nil, t or `lambda'.  So the most we can say from this doc is that the
function performs completion ACTION, which is nil, t, or `lambda'.
 
How it "performs" nil, t, or `lambda', and what that could possibly
mean, is a wonder.  What it really performs is completion, according to
ACTION.
 
The doc string should at least say that it performs completion, and that
STRING, TABLE, and PRED are used as in `try-completion',
`all-completions', and `test-completion'.  (And make the connection
TABLE <-> COLLECTION, since the parameter names are different, enhancing
confusion.)
 
IOW, at the very LEAST, refer the reader to things that ARE documented.
 
The doc of `complete-with-action' should do more, however.  It should
say what it does:
 
If TABLE is a function then TABLE does all of the completing.  It is
passed arguments STRING, PRED, and ACTION. (and refer to (or copy)
existing doc about this).
 
Else the behavior depends on the value of ACTION:
 
 If `metadata' or a cons with car `boundaries' then return nil.
 If nil, return (try-completion STRING TABLE PRED).
 If t,   return (all-completions STRING TABLE PRED).
 Else    return (test-completion STRING TABLE PRED).
 
Maybe you can think of something better to say.  (The function seems a
bit artificial, which is perhaps why one cannot say easily what it does,
other than by echoing the implementation.)
 
That's just a suggestion - SOME real description is needed, to help
users use this function.

In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-03-04 on ODIEONE
Bzr revision: 111935 yamaoka@HIDDEN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 





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#13993; 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.