From unknown Tue Jun 24 13:59:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#13993: 24.3.50; doc of `complete-with-action' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 18 Mar 2013 21:30:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 13993 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 13993@debbugs.gnu.org X-Debbugs-Original-To: Received: via spool by submit@debbugs.gnu.org id=B.136364214831893 (code B ref -1); Mon, 18 Mar 2013 21:30:02 +0000 Received: (at submit) by debbugs.gnu.org; 18 Mar 2013 21:29:08 +0000 Received: from localhost ([127.0.0.1]:34170 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UHhcC-0008IL-5j for submit@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 ) id 1UHhcA-0008IE-1g for submit@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 ) id 1UHhaa-0005xU-Us for submit@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 ) id 1UHhaa-0005xP-Rl for submit@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 ) id 1UHhaW-0005ch-Q8 for bug-gnu-emacs@gnu.org; Mon, 18 Mar 2013 17:27:28 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UHhaV-0005wM-Fz for bug-gnu-emacs@gnu.org; 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 ) id 1UHhaV-0005w4-AP for bug-gnu-emacs@gnu.org; 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 ; 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 ; 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 ; 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" Date: Mon, 18 Mar 2013 14:27:17 -0700 Message-ID: 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@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@jpl.org-20130304102733-4qy111z41qwoh2as 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' From unknown Tue Jun 24 13:59:10 2025 X-Loop: help-debbugs@gnu.org Subject: bug#13993: 24.3.50; doc of `complete-with-action' Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 15 Aug 2019 05:45:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13993 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 13993@debbugs.gnu.org Received: via spool by 13993-submit@debbugs.gnu.org id=B13993.156584789110530 (code B ref 13993); Thu, 15 Aug 2019 05:45:01 +0000 Received: (at 13993) by debbugs.gnu.org; 15 Aug 2019 05:44:51 +0000 Received: from localhost ([127.0.0.1]:50406 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hy8Z8-0002jm-N0 for submit@debbugs.gnu.org; Thu, 15 Aug 2019 01:44:50 -0400 Received: from quimby.gnus.org ([80.91.231.51]:35910) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hy8Z6-0002ja-5U for 13993@debbugs.gnu.org; Thu, 15 Aug 2019 01:44:48 -0400 Received: from 24-104-73-23-ip-static.hfc.comcastbusiness.net ([24.104.73.23] helo=sandy) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hy8Z1-0008Ix-OE; Thu, 15 Aug 2019 07:44:46 +0200 From: Lars Ingebrigtsen References: Date: Wed, 14 Aug 2019 22:44:41 -0700 In-Reply-To: (Drew Adams's message of "Mon, 18 Mar 2013 14:27:17 -0700") Message-ID: <87zhkbyoc6.fsf@mouse.gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: "Drew Adams" writes: > 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 [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) "Drew Adams" writes: > 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). I've now altered the doc string along the lines of what you suggest, but less verbose. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Thu Aug 15 01:45:00 2019 Received: (at control) by debbugs.gnu.org; 15 Aug 2019 05:45:00 +0000 Received: from localhost ([127.0.0.1]:50409 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hy8ZH-0002kB-VR for submit@debbugs.gnu.org; Thu, 15 Aug 2019 01:45:00 -0400 Received: from quimby.gnus.org ([80.91.231.51]:35924) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hy8ZH-0002k4-6I for control@debbugs.gnu.org; Thu, 15 Aug 2019 01:44:59 -0400 Received: from 24-104-73-23-ip-static.hfc.comcastbusiness.net ([24.104.73.23] helo=sandy) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hy8ZE-0008J4-9j for control@debbugs.gnu.org; Thu, 15 Aug 2019 07:44:58 +0200 Date: Wed, 14 Aug 2019 22:44:54 -0700 Message-Id: <87y2zvyobt.fsf@mouse.gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #13993 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: tags 13993 fixed close 13993 27.1 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) tags 13993 fixed close 13993 27.1 quit