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

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

[Shynur Xie]

[-- 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

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

[Eli Zaretskii]

> From: Shynur Xie <one.last.kiss@outlook.com>
> Date: Tue, 13 Jun 2023 13:36:50 +0000
> msip_labels: 
> 
> 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.

Thanks, but the text you suggest reads as more complex and harder to
understand.  So how about explaining what was wrong or missing or
unclear in the original text?  Then I could come up with a better
wording.

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

[Shynur Xie]

>    From: Eli Zaretskii <eliz@gnu.org>
>    Date: Tue, 13 Jun 2023 16:46:47 +0300
> Subject: Re: bug#64045
>      To: Shynur Xie <one.last.kiss@outlook.com>
>
> So how about explaining what was wrong or missing or unclear in the
> original text?

You can read these 2 posts (very short and won't take up much of your
time):

- Question: Effect of `modes` In Declare Form
  https://emacs.stackexchange.com/questions/77597
- Question: `completion` In Declare Form Not Working
  https://emacs.stackexchange.com/questions/77599

Thanks.

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

[Eli Zaretskii]

> From: Shynur Xie <one.last.kiss@outlook.com>
> CC: "64045@debbugs.gnu.org" <64045@debbugs.gnu.org>
> Date: Tue, 13 Jun 2023 13:54:26 +0000
> msip_labels:
> 
> >    From: Eli Zaretskii <eliz@gnu.org>
> >    Date: Tue, 13 Jun 2023 16:46:47 +0300
> > Subject: Re: bug#64045
> >      To: Shynur Xie <one.last.kiss@outlook.com>
> >
> > So how about explaining what was wrong or missing or unclear in the
> > original text?
> 
> You can read these 2 posts (very short and won't take up much of your
> time):
> 
> - Question: Effect of `modes` In Declare Form
>   https://emacs.stackexchange.com/questions/77597
> - Question: `completion` In Declare Form Not Working
>   https://emacs.stackexchange.com/questions/77599

Thanks, I've clarified these now on the emacs-29 branch.

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

[Eli Zaretskii]

> Cc: 64045@debbugs.gnu.org
> Date: Thu, 15 Jun 2023 09:29:48 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Shynur Xie <one.last.kiss@outlook.com>
> > CC: "64045@debbugs.gnu.org" <64045@debbugs.gnu.org>
> > Date: Tue, 13 Jun 2023 13:54:26 +0000
> > msip_labels:
> > 
> > >    From: Eli Zaretskii <eliz@gnu.org>
> > >    Date: Tue, 13 Jun 2023 16:46:47 +0300
> > > Subject: Re: bug#64045
> > >      To: Shynur Xie <one.last.kiss@outlook.com>
> > >
> > > So how about explaining what was wrong or missing or unclear in the
> > > original text?
> > 
> > You can read these 2 posts (very short and won't take up much of your
> > time):
> > 
> > - Question: Effect of `modes` In Declare Form
> >   https://emacs.stackexchange.com/questions/77597
> > - Question: `completion` In Declare Form Not Working
> >   https://emacs.stackexchange.com/questions/77599
> 
> Thanks, I've clarified these now on the emacs-29 branch.

No further comments, so I'm now closing this bug.