From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 23 Jul 2022 09:54:07 +0000 (+0300)
Subject: Update the documentation of 'declare' forms
X-Git-Tag: emacs-28.1.91~23
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=54c4ceb0091e0d3190755afbd7875864cd91b730;p=emacs.git

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

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 335200469b2..f336753a6c3 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 06d50311799..28893875062 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