bug#13993: 24.3.50; doc of `complete-with-action'

[Drew Adams]

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'