From 70fc7c41ef393078001ca339f6abe02776f2e2ae Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 15 Jun 2023 09:28:26 +0300 Subject: [PATCH] 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 -- 2.39.2