completing-read, incomplete documentation for "programmed completion"

completing-read, incomplete documentation for "programmed completion"

[Ulrich Mueller]

Hi,

I think that the documentation of `completing-read' should be
improved, with respect to "programmed completion". Currently, its
docstring says about the subject:

,----
| COLLECTION can also be a function to do the completion itself.
| PREDICATE limits completion to a subset of COLLECTION.
| See `try-completion' and `all-completions' for more details
|  on completion, COLLECTION, and PREDICATE.
`----

Now the docstrings of `try-completion' and `all-completions' (and
`test-completion', which is not mentioned for some reason) just say
that `nil', `t', or `lambda' will be passed as the third argument to
the completion function, respectively.

However, if I evaluate the following expression:
   (completing-read "Prompt: " 'debug)

and type TAB in the minibuffer, the debugger shows that neither `nil'
nor `t' nor `lambda' are passed, but that the third argument is
`(boundaries . "")'.

The debugger also shows that it is called by `completion-boundaries',
but the docstring of this function (which didn't exist in Emacs 22?)
is not helpful at all.

Am I missing something? IMHO, `completing-read' should explain its
COLLECTION argument, and should also explain what are the possible
arguments passed to the completion function.

(BTW, also the Elisp Reference Manual mentions only `nil', `t', and
`lambda' in section 20.6.6, "Programmed Completion".)

Ulrich

Re: completing-read, incomplete documentation for "programmed completion"

[Stefan Monnier]

> (BTW, also the Elisp Reference Manual mentions only `nil', `t', and
> `lambda' in section 20.6.6, "Programmed Completion".)

...and the etc/NEWS file mentions that completion-boundaries is new and
is not yet documented in the Elisp manual.


        Stefan

Re: completing-read, incomplete documentation for "programmed completion"

[Ulrich Mueller]

>>>>> On Sun, 04 Jan 2009, Stefan Monnier wrote:

> ...and the etc/NEWS file mentions that completion-boundaries is new
> and is not yet documented in the Elisp manual.

Yeah, but the Elisp manual was not my point. I was mainly speaking
about the functions' docstrings.

Here is another one, `complete-with-action', where the docstring does
not agree with the code:

,----
| (complete-with-action ACTION TABLE STRING PRED)
| 
| Perform completion ACTION.
| STRING is the string to complete.
| TABLE is the completion table, which should not be a function.
| PRED is a completion predicate.
| ACTION can be one of nil, t or `lambda'.
`----

Also, the different behaviour of `completing-read' breaks backwards
compatibility. In fact, I stumbled across this because of some lisp
code doing "programmed completion", which doesn't work properly with
Emacs 23 anymore (because it accounts only for nil, t, and `lambda').

So I think that proper documentation is important here.

Ulrich

Re: completing-read, incomplete documentation for "programmed completion"

[Stefan Monnier]

> Also, the different behaviour of `completing-read' breaks backwards
> compatibility. In fact, I stumbled across this because of some lisp
> code doing "programmed completion", which doesn't work properly with
> Emacs 23 anymore (because it accounts only for nil, t, and `lambda').

The intention is for it to 100% backwards compatible.  So please report
this bug.


        Stefan