* completing-read, incomplete documentation for "programmed completion"
@ 2009-01-05 0:59 Ulrich Mueller
2009-01-05 2:18 ` Stefan Monnier
0 siblings, 1 reply; 4+ messages in thread
From: Ulrich Mueller @ 2009-01-05 0:59 UTC (permalink / raw)
To: emacs-devel
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: completing-read, incomplete documentation for "programmed completion"
2009-01-05 0:59 completing-read, incomplete documentation for "programmed completion" Ulrich Mueller
@ 2009-01-05 2:18 ` Stefan Monnier
2009-01-05 9:17 ` Ulrich Mueller
0 siblings, 1 reply; 4+ messages in thread
From: Stefan Monnier @ 2009-01-05 2:18 UTC (permalink / raw)
To: Ulrich Mueller; +Cc: emacs-devel
> (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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: completing-read, incomplete documentation for "programmed completion"
2009-01-05 2:18 ` Stefan Monnier
@ 2009-01-05 9:17 ` Ulrich Mueller
2009-01-05 22:13 ` Stefan Monnier
0 siblings, 1 reply; 4+ messages in thread
From: Ulrich Mueller @ 2009-01-05 9:17 UTC (permalink / raw)
To: Stefan Monnier; +Cc: emacs-devel
>>>>> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: completing-read, incomplete documentation for "programmed completion"
2009-01-05 9:17 ` Ulrich Mueller
@ 2009-01-05 22:13 ` Stefan Monnier
0 siblings, 0 replies; 4+ messages in thread
From: Stefan Monnier @ 2009-01-05 22:13 UTC (permalink / raw)
To: Ulrich Mueller; +Cc: emacs-devel
> 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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2009-01-05 22:13 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2009-01-05 0:59 completing-read, incomplete documentation for "programmed completion" Ulrich Mueller
2009-01-05 2:18 ` Stefan Monnier
2009-01-05 9:17 ` Ulrich Mueller
2009-01-05 22:13 ` Stefan Monnier
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.