Re: completion-all-completions-with-base-size

[Stefan Monnier <monnier@iro.umontreal.ca>]

> This NEWS entry:
>     *** `all-completions' may now return the base size in the last cdr.
>     Since this means the returned list is not properly nil-terminated, this
>     is an incompatible change and is thus enabled by the new variable
>     completion-all-completions-with-base-size.

> is inaccurate: `all-completions' does not take into account the value
> of `completion-all-completions-with-base-size'.

IIUC, this is not relevant: the base-size is always 0 (in which case
it's not necessary to add it) for all completion tables except
functional ones.  So of course all-completions doesn't take it into
account: only the functional completion tables do.

Still, the value returned by all-completions can contains such `cdr's
and it depends on completion-all-completions-with-base-size.

> Only `completion-all-completions' and a couple of internal functions
> consult that variable.

`completion-all-completions' does not consult it: it sets it.

> But `completion-all-completions' is not documented in the ELisp
> manual, as are most of other APIs in minibuffer.el (should they be
> documented?),

I don't see why they should be documented there.  The entry points are
the same as before (and are documented): minibuffer-complete,
minibuffer-complete-word, ...

> so it sounds like the above NEWS entry does not warrant any
> documentation in the manuals?  Why then it was added to NEWS?

Because some functions may call all-completions in a context where
someone has set completion-all-completions-with-base-size
(e.g. when all-completions is used internally by a functional
completion table), in which case it may be surprised by the extra `cdr'
(which could cause `length' or `mapcar' to signal an error).

I hope to be able to find the time to revisit this specific
completion-all-completions-with-base-size before the release, because
I believe that with the `boundaries' thingy I added later,
completion-all-completions-with-base-size might have become unnecessary.


        Stefan