emacs-29 70fc7c41ef3: Improve documentation of 'declare' forms

[Eli Zaretskii]

branch: emacs-29
commit 70fc7c41ef393078001ca339f6abe02776f2e2ae
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of 'declare' forms
    
    * lisp/simple.el (read-extended-command-predicate): Mention the
    '(declare completion ...' form in the doc string.
    
    * doc/lispref/functions.texi (Declare Form): Clarify
    'completion-predicate' and 'modes'; add cross-references.
    (Bug#64045)
---
 doc/lispref/functions.texi | 16 ++++++++++------
 lisp/simple.el             |  5 ++++-
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index fc902a70bf0..e646e7c8b0a 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2609,14 +2609,18 @@ be passed to @code{gv-define-setter}.
 
 @item (completion @var{completion-predicate})
 Declare @var{completion-predicate} as a function to determine whether
-to include the symbol in the list of functions when asking for
-completions in @kbd{M-x}.  @var{completion-predicate} is called with
-two parameters: The first parameter is the symbol, and the second is
-the current buffer.
+to include a function's symbol in the list of functions when asking
+for completions in @kbd{M-x}.  This predicate function will only be
+called when @code{read-extended-command-predicate} is customized to
+@code{command-completion-default-include-p}; by default the value of
+@code{read-extended-command-predicate} is nil (@pxref{Interactive
+Call, execute-extended-command}).  The predicate
+@var{completion-predicate} is called with two arguments: the
+function's symbol and the current buffer.
 
 @item (modes @var{modes})
-Specify that this command is meant to be applicable for @var{modes}
-only.
+Specify that this command is meant to be applicable only to specified
+@var{modes}.  @xref{Command Modes}.
 
 @item (interactive-args @var{arg} ...)
 Specify the arguments that should be stored for @code{repeat-command}.
diff --git a/lisp/simple.el b/lisp/simple.el
index 9df5958a168..406f1008df3 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2225,7 +2225,10 @@ are available:
          This excludes from completion candidates those commands
          which have been marked specific to modes other than the
          current buffer's mode.  Commands that are not specific
-         to any mode are included.
+         to any mode are included.  If a command has a
+         `(declare completion...' form which specifies a predicate,
+         that predicate will be called to determine whether to
+         include the command in the completion candidates.
 
   `command-completion-using-modes-p'
          This includes in completion candidates only commands