Subject: Re: bug#77649: [PATCH] Add support for updating *Completions* as you type

From: Eli Zaretskii <[email-masked]>
Date: Tue, 22 Jul 2025 15:22:34 +0300

> Cc: [email-masked], [email-masked],
>  Daniel Mendler <[email-masked]>
> Date: Mon, 21 Jul 2025 12:43:56 -0400
> From:  Spencer Baugh via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> +*** New user option 'completion-eager-update.
                                               ^
Closing quote missing there.

> +This option configures whether typing should update the contents of the
               ^^^^^^^^^^
We normally use "controls".

> +"*Completions*" buffer, if it is shown.  When the option is set to t,
> +typing will always update the "*Completions*" buffer.  Note that for
> +large or inefficient completion tables, this can slow down typing.  The
> +default setting enables eager updating only if requested by the command.
> +For more fine-grained control you can also toggle this feature by
> +category using the symbol 'eager-update in the user option
> +'completion-category-overrides'.

IMO, the last two sentences are too vague/mysterious to be useful
(this is a user option, remember?)

> +If `auto', only update if the completion table has requested it or
> +`eager-update' is set in in `completion-category-defaults'.

This should at least hint how would a completion table request the
update, or mention some function or variable whose doc string explains
that.

The doc string should also describe what happens when the value is nil.

> +  :type '(choice (const :tag "Do nothing when you type" nil)

"Do nothing" is incorrect.  I think you mean "Do not update
completions" or somesuch.

Thanks.