Re: Documentation about the completion framework

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

> Unfortunately docstring of the relevant elisp functions are not always
> detailed and in some cases not complete. I would also really appreciate
> some documentation on how the framework can be used and how is it
> supposed to be used, even better if there would be some hints on how to
> keep it efficient.
>
> Does such documentation exist somewhere? Does anyone have any resource
> to recommend?

It's mostly available in docstrings.
For example, C-h o completion-at-point-functions says:

    [...]
    NOTE: These functions should be cheap to run since they’re sometimes
    run from ‘post-command-hook’; and they should ideally only choose
    which kind of completion table to use, and not pre-filter it based
    on the current text between START and END (e.g., they should not
    obey ‘completion-styles’).

> One specific question I have: in some circumstances completion-at-point
> enters a mode in which it is called for each keystroke (I think this is
> completion-in-region-mode). How does this happen and why?  I would like
> to avoid that my function to collect completion targets get called on
> each keystroke. Is there a way to do that?

Yes: don't collect candidates when that function is called.
Instead, the function should return a completion table which will
compute the candidates only if it's called.  E.g.:

    (defun my-completion-at-point-function ()
      (when (relevant)
        (let (candidates
              (candidates-computed nil)
              (start ...)
              (end ...)
              (completion-table
               (lambda (string pred action)
                 (unless candidates-computed
                   (setq candidates-computed t)
                   (setq candidates (my-collect-candidates)))
                 (complete-with-action action candidates string pred))))
          (list start end completion-table))))

tho you probably want to cache your completion candidates elsewhere
(exactly where to cache them depends on when they need to be
recomputed, so often it's best to cache them in a global variable and
flush them from other places in the code).


        Stefan