emacs-28 54c4ceb009 1/2: Update the documentation of 'declare' forms

[Eli Zaretskii]

branch: emacs-28
commit 54c4ceb0091e0d3190755afbd7875864cd91b730
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Update the documentation of 'declare' forms
    
    * doc/lispref/compile.texi (Native-Compilation Variables): Mention
    the 'declare' alternative for 'native-comp-speed'.
    * doc/lispref/functions.texi (Declare Form): Document 'declare'
    forms that were previously undocumented.
---
 doc/lispref/compile.texi   |  4 +++-
 doc/lispref/functions.texi | 24 ++++++++++++++++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 335200469b..f336753a6c 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -985,7 +985,9 @@ corresponding compiler @option{-O0}, @option{-O1}, etc.@: 
command-line
 options of the compiler.  The value @minus{}1 means disable
 native-compilation: functions and files will be only byte-compiled;
 however, the @file{*.eln} files will still be produced, they will just
-contain the compiled code in bytecode form.
+contain the compiled code in bytecode form.  (This can be achieved at
+function granularity by using the @w{@code{(declare (speed -1))}}
+form, @pxref{Declare Form}.)
 The default value is 2.
 @end defopt
 
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 06d5031179..2889387506 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2333,6 +2333,30 @@ the current buffer.
 @item (modes @var{modes})
 Specify that this command is meant to be applicable for @var{modes}
 only.
+
+@item (pure @var{val})
+If @var{val} is non-@code{nil}, this function is @dfn{pure}
+(@pxref{What Is a Function}).  This is the same as the @code{pure}
+property of the function's symbol (@pxref{Standard Properties}).
+
+@item (side-effect-free @var{val})
+If @var{val} is non-@code{nil}, this function is free of side effects,
+so the byte compiler can ignore calls whose value is ignored.  This is
+the same as the @code{side-effect-free} property of the function's
+symbol, @pxref{Standard Properties}.
+
+@item (speed @var{n})
+Specify the value of @code{native-comp-speed} in effect for native
+compilation of this function (@pxref{Native-Compilation Variables}).
+This allows function-level control on the optimization level used for
+native code emitted for the function.  In particular, if @var{n} is
+@minus{}1, native compilation of the function will emit bytecode
+instead of native code for the function.
+
+@item no-font-lock-keyword
+This is valid for macros only.  Macros with this declaration are
+highlighted by font-lock (@pxref{Font Lock Mode}) as normal functions,
+not specially as macros.
 @end table
 
 @end defmac