bug#7499: Documentation: `comint-dynamic-list-filename-completions'

[MON KEY]

On Sat, Nov 27, 2010 at 1:35 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:

> The term "help buffer" is apparently used here loosely to mean
> "auxiliary buffer helpful to the user".
>

Its less than apparent (to me at least) that such loose usage is helpful. :)

AFAICT `comint-dynamic-list-completions' is hardwired to "*Completions*".

Its docstring is equally suspect:

,---- (documentation 'comint-dynamic-list-completions)
|
|     List in help buffer sorted completions.  The meaning of
|     common-substring is the same as in `display-completion-list'.
|     Typing SPC flushes the help buffer.
|
`----

W/re `comint-dynamic-list-completions',
`comint-dynamic-list-filename-completions' (and any other similar such
comint docstrings), what would prob. be more "helpful to the user"
would be to explicitly document that return value is to
"*Completions*". :)

After all, there is no provision for an alternative destination
stream.  Indeed, it is doubtful such alternatives could be made
available via `comint-dynamic-list-completions' given the complicated
interactions between windows/buffers/configurations and the dynamic bindings of
`standard-output' happening around the internal calls to
`display-completion-list' and `with-output-to-temp-buffer'.

>        Stefan

--
/s_P\