Merge from emacs-24; up to 2014-06-12T14:55:48Z!monnier@iro.umontreal.ca

[bpt/emacs.git] / doc / lispref / minibuf.texi

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 4a94f41..e76b827 100644 (file)
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1736,7 +1736,7 @@ possible match, and ignore the match if the predicate returns
 
 @item
 A flag specifying the type of completion operation to perform.  This
-is one of the following four values:
+flag may be one of the following values.
 
 @table @code
 @item nil
@@ -1875,11 +1875,34 @@ next function in @code{completion-at-point-functions} instead of
 reporting a completion failure.
 @end table
 
+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}
+many times, but care about the value of @var{collection} for only some
+of these calls.  By supplying a function for @var{collection}, Emacs
+can defer generating completions until necessary.  You can use
+@var{completion-table-dynamic} to create a wrapper function:
+
+@smallexample
+;; Avoid this pattern.
+(let ((beg ...) (end ...) (my-completions (my-make-completions)))
+  (list beg end my-completions))
+
+;; Use this instead.
+(let ((beg ...) (end ...))
+  (list beg
+        end
+        (completion-table-dynamic
+          (lambda (_)
+            (my-make-completions)))))
+@end smallexample
+
 A function in @code{completion-at-point-functions} may also return a
-function.  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 @code{completion-at-point}.
+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
+@code{completion-at-point}.
 
 The first function in @code{completion-at-point-functions} to return a
 non-@code{nil} value is used by @code{completion-at-point}.  The