Extend the syntax of `interactive' to list applicable modes

* doc/lispref/commands.texi (Using Interactive): Document the
extended `interactive' form.
* doc/lispref/loading.texi (Autoload): Document list-of-modes
form.

* lisp/emacs-lisp/autoload.el (make-autoload): Pick the list of
modes from `interactive' out of the functions.

* lisp/emacs-lisp/bytecomp.el (byte-compile-lambda): Allow for the
extended `interactive' form.

* src/callint.c (Finteractive): Document the extended form.

* src/data.c (Finteractive_form): Return the interactive form in
the old format (even when there's an extended `interactive') to
avoid having other parts of Emacs be aware of this.
(Fcommand_modes): New defun.

* src/emacs-module.c (GCALIGNED_STRUCT): Allow for modules to
return command modes.

* src/lisp.h: New function module_function_command_modes.

1 files changed, 18 insertions, 1 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 3a2c7d019ef..d60745a825b 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -156,7 +156,7 @@ commands by adding the @code{interactive} form to them.
 makes a Lisp function an interactively-callable command, and how to
 examine a command's @code{interactive} form.
 
-@defspec interactive arg-descriptor
+@defspec interactive &optional arg-descriptor &rest modes
 This special form declares that a function is a command, and that it
 may therefore be called interactively (via @kbd{M-x} or by entering a
 key sequence bound to it).  The argument @var{arg-descriptor} declares
@@ -177,6 +177,23 @@ forms are executed; at this time, if the @code{interactive} form
 occurs within the body, the form simply returns @code{nil} without
 even evaluating its argument.
 
+The @var{modes} list allows specifying which modes the command is
+meant to be used in.  This affects, for instance, completion in
+@kbd{M-x} (commands won't be offered as completions if they don't
+match (using @code{derived-mode-p}) the current major mode, or if the
+mode is a minor mode, whether it's switched on in the current buffer).
+This will also make @kbd{C-h m} list these commands (if they aren't
+bound to any keys).
+
+For instance:
+
+@lisp
+(interactive "p" dired-mode)
+@end lisp
+
+This will mark the command as applicable for modes derived from
+@code{dired-mode} only.
+
 By convention, you should put the @code{interactive} form in the
 function body, as the first top-level form.  If there is an
 @code{interactive} form in both the @code{interactive-form} symbol