bug#64045: [PATCH] Improve wording of the documentation about declare form

[Shynur Xie <one.last.kiss@outlook.com>]

[-- Attachment #1: Type: text/plain, Size: 402 bytes --]

I modified section 13.14 (The declare form) of the GNU Emacs Lisp
Reference Manual.  The manual didn't say how to make

    (declare (completion ...)
             (modes ...))

take effect; the original text is even somewhat misleading.  Simply
evaluating a (defun ...) form which includes the above declare form
won't make Emacs filter commands when asking for completion in M-x.

--
shynur

[-- Attachment #2: 0001-Improve-wording-of-the-documentation-about-declare-f.patch --]
[-- Type: application/octet-stream, Size: 2503 bytes --]

From 36ed6cf7b74b33cb4df2b28950736854eddcdbf3 Mon Sep 17 00:00:00 2001
From: Shynur <one.last.kiss@outlook.com>
Date: Tue, 13 Jun 2023 21:14:37 +0800
Subject: [PATCH] ; Improve wording of the documentation about declare form

---
 doc/lispref/functions.texi | 20 +++++++++++---------
 lisp/simple.el             |  5 ++++-
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index a94fdee1d82..68296dd437a 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2613,15 +2613,17 @@ additionally have access to the macro (or function)'s arguments and it will
 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.
-
-@item (modes @var{modes})
-Specify that this command is meant to be applicable for @var{modes}
-only.
+Declare @var{completion-predicate} as a function to determine, when
+option @code{read-extended-command-predicate} is set to
+@code{command-completion-default-include-p}, 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.
+
+@item (modes @var{mode} ...)
+Specify that this command is meant to be applicable for @var{mode}s
+only.  See @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 e08bf4fdd64..30410cde4c2 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2226,7 +2226,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 there's a
+         `completion-predicate' for a command, this command is
+         excluded as well if the result calling from its predicate
+         is nil.
 
   `command-completion-using-modes-p'
          This includes in completion candidates only commands
-- 
2.39.1