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

2 files changed, 18 insertions, 6 deletions

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 0ef81858ea9..b01ebb26b69 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -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
 completion tables (@pxref{Major Mode Conventions}).
 
-When the command @code{completion-at-point} runs, it calls the
-functions in the list one by one, without any argument.  Each function
-should return @code{nil} if it is unable to produce a completion table
-for the text at point.  Otherwise it should return a list of the form
+When the command @code{completion-at-point} runs, it calls the functions in the
+list one by one, without any argument.  Each function should return @code{nil}
+unless it can and wants to take responsibility for the completion data for the
+text at point.  Otherwise it should return a list of the form
 
 @example
 (@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.
 @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
 generating the list of completions is an expensive operation.  Emacs
 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)))))
 @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
 function instead of a list as described above.  In that case, that
 returned function is called, with no argument, and it is entirely
 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}.
 
 The first function in @code{completion-at-point-functions} to return a
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 3227917494e..6eded9c58fe 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -2072,7 +2072,12 @@ Currently supported properties are all the properties that can appear in
    match the text at point, then instead of reporting a completion
    failure, the completion should try the next completion function.
 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
   "List of functions found on `completion-at-point-functions' that misbehave.