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

Previous Next

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

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

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.3.50; doc of `complete-with-action'
Date: Mon, 18 Mar 2013 14:27:17 -0700

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13993 <at> debbugs.gnu.org
Subject: Re: bug#13993: 24.3.50; doc of `complete-with-action'
Date: Wed, 14 Aug 2019 22:44:41 -0700

"Drew Adams" <drew.adams <at> oracle.com> 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

Previous Next

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