Improve documentation of COLLECTION in completion functions

* doc/lispref/minibuf.texi (Minibuffer Completion): Add a
cross-reference to "Programmed Completion".

* src/minibuf.c (Fcompleting_read): Improve the doc string.
(Bug#21644)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 96c1020d748ecbef613e5ec2a37013d37e7500f8..0b1a4a90ba9979825fb945966efb25e055745e09 100644 (file)
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -975,6 +975,9 @@ Thus, if @var{predicate} is non-@code{nil}, it should be compatible
 with @var{collection} and @code{completion-ignore-case}.
 @xref{Definition of test-completion}.
 
+@xref{Programmed Completion}, for detailed requirements when
+@var{collection} is a function.
+
 The value of the optional argument @var{require-match} determines how
 the user may exit the minibuffer:
 

diff --git a/src/minibuf.c b/src/minibuf.c
index 2cde8b097bee40f29b5c0ec0272796fa50a68dbe..e149e81941312fd89ce2775b4e21f83129cda9d5 100644 (file)
--- a/src/minibuf.c
+++ b/src/minibuf.c
@@ -1595,8 +1595,11 @@ PROMPT is a string to prompt with; normally it ends in a colon and a space.
 COLLECTION can be a list of strings, an alist, an obarray or a hash table.
 COLLECTION can also be a function to do the completion itself.
 PREDICATE limits completion to a subset of COLLECTION.
-See Info node `(elisp)Basic Completion' for more details
- on completion, COLLECTION, and PREDICATE.
+See `try-completion', `all-completions', `test-completion',
+and `completion-boundaries', for more details on completion,
+COLLECTION, and PREDICATE.  See also Info nodes `(elisp)Basic Completion'
+for the details about completion, and `(elisp)Programmed Completion' for
+expectations from COLLECTION when it's a function.
 
 REQUIRE-MATCH can take the following values:
 - t means that the user is not allowed to exit unless