procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(completion-at-point-functions): Improve doc

Browse source 
(cherry picked from commit b56c56f203)
This commit is contained in:
Stefan Monnier 2018-03-27 16:01:30 -04:00 • committed by Eli Zaretskii
parent af1624f29b
commit 748f0fdd5a
2 changed files with 18 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
doc/lispref/minibuf.texi
View file

@ -1877,10 +1877,10 @@ are used to compute a completion table for completing the text at
point. It can be used by major modes to provide mode-specific point. It can be used by major modes to provide mode-specific
completion tables (@pxref{Major Mode Conventions}). completion tables (@pxref{Major Mode Conventions}).
When the command @code{completion-at-point} runs, it calls the When the command @code{completion-at-point} runs, it calls the functions in the
functions in the list one by one, without any argument. Each function list one by one, without any argument. Each function should return @code{nil}
should return @code{nil} if it is unable to produce a completion table unless it can and wants to take responsibility for the completion data for the
for the text at point. Otherwise it should return a list of the form text at point. Otherwise it should return a list of the form
@example @example
(@var{start} @var{end} @var{collection} . @var{props}) (@var{start} @var{end} @var{collection} . @var{props})
@ -1910,6 +1910,8 @@ next function in @code{completion-at-point-functions} instead of
reporting a completion failure. reporting a completion failure.
@end table @end table
The functions on this hook should generally return quickly, since they may be
called very often (e.g., from @code{post-command-hook}).
Supplying a function for @var{collection} is strongly recommended if Supplying a function for @var{collection} is strongly recommended if
generating the list of completions is an expensive operation. Emacs generating the list of completions is an expensive operation. Emacs
may internally call functions in @code{completion-at-point-functions} may internally call functions in @code{completion-at-point-functions}
@ -1932,11 +1934,16 @@ can defer generating completions until necessary. You can use
(my-make-completions))))) (my-make-completions)))))
@end smallexample @end smallexample
Additionally, the @var{collection} should generally not be pre-filtered based
on the current text between @var{start} and @var{end}, because that is the
responsibility of the caller of @code{completion-at-point-functions} to do that
according to the completion styles it decides to use.
A function in @code{completion-at-point-functions} may also return a A function in @code{completion-at-point-functions} may also return a
function instead of a list as described above. In that case, that function instead of a list as described above. In that case, that
returned function is called, with no argument, and it is entirely returned function is called, with no argument, and it is entirely
responsible for performing the completion. We discourage this usage; responsible for performing the completion. We discourage this usage;
it is intended to help convert old code to using it is only intended to help convert old code to using
@code{completion-at-point}. @code{completion-at-point}.
The first function in @code{completion-at-point-functions} to return a The first function in @code{completion-at-point-functions} to return a

7
lisp/minibuffer.el
View file

@ -2076,7 +2076,12 @@ Currently supported properties are all the properties that can appear in
match the text at point, then instead of reporting a completion match the text at point, then instead of reporting a completion
failure, the completion should try the next completion function. failure, the completion should try the next completion function.
As is the case with most hooks, the functions are responsible for As is the case with most hooks, the functions are responsible for
preserving things like point and current buffer.") preserving things like point and current buffer.
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. that would not obey `completion-styles').")
(defvar completion--capf-misbehave-funs nil (defvar completion--capf-misbehave-funs nil
"List of functions found on `completion-at-point-functions' that misbehave. "List of functions found on `completion-at-point-functions' that misbehave.