; Fix documentation of recently-installed changes

* lisp/emacs-lisp/bytecomp.el (compilation-safety): Doc fix.

* etc/NEWS: Fix wording of the 'compilation-safety' entry.

* doc/lispref/functions.texi (Declare Form): Fix cross-reference
and wording.
* doc/lispref/compile.texi (Native-Compilation Variables): Add the
missing @anchor.  Fix wording.

(cherry picked from commit f6d060b39a02da14aa1763bb688cb2e048f0c666)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index f8f1242586e0eb5220fafe3fd050e232fef74fab..9f93fb4a981443892702ab0a3abd8ba5e2a54b0f 100644 (file)
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -987,21 +987,23 @@ form, @pxref{Declare Form}.)
 The default value is 2.
 @end defopt
 
+@anchor{compilation-safety}
 @defopt compilation-safety
-This variable specifies the safetyness level used for the code emitted
-native code.  The value of compilation-safety should be a number between
-zero and one with the following meaning:
+This variable specifies the safety level to be used for the emitted
+native code.  The value should be a number, either 0 or 1 with the
+following meanings:
 
 @table @asis
 @item 0
-Emitted code can misbehave or crash Emacs if function declarations are
-not correct and the function is native compiled.
+Emitted code can misbehave (up to even crashing Emacs) if a function's
+declaration does not describe correctly what the function does or how it
+is called, and the function is natively compiled.
 @item 1
-Emitted code is generated in a safe matter even if function are
-miss-declared."
+Emitted code must be generated in a safe manner even if functions are
+mis-declared.
 @end table
 
-This can be controlled at function granularity as well by using the
+This can also be controlled at a function granularity, by using the
 @code{safety} @code{declare} form, @pxref{Declare Form}.
 @end defopt
 

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 9d4ecd8da250c607953f3bef80eab92c7443c63b..deca99960c75a5da8572824c70f2a60a1d4324d7 100644 (file)
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2761,10 +2761,11 @@ argument of type @var{string} and return one of the symbols
 For description of additional types, see @ref{Lisp Data Types}).
 
 Declaring a function with an incorrect type produces undefined behavior
-and could lead to unexpected results or might even crash Emacs when code
-is native-compiled and loaded if compiled with @ref{compilation-safety}
-0.  Note also that when redefining (or advising) a type declared
-function the replacement should respect the original signature to avoid
+and could lead to unexpected results or might even crash Emacs when
+natively-compiled code is loaded, if it was compiled with
+@code{compilation-safety} level of zero (@pxref{compilation-safety}).
+Note also that when redefining (or advising) a type-declared function,
+the replacement should respect the original signature to avoid such
 undefined behavior.
 
 @item no-font-lock-keyword

diff --git a/etc/NEWS b/etc/NEWS
index 1258461661c922cda97a4b12df1857a1f70ed316..0ffbb9a69c6c28962f464e171c804d53d24e135f 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2103,9 +2103,11 @@ unibyte string.
 \f
 * Lisp Changes in Emacs 30.1
 +++
-** New 'compilation-safety' compilation parameter.
-It's now possible to use the safety parameter to control how safe is
-code generated by the native compiler.
+** New user option 'compilation-safety' to control safety of native code.
+It's now possible to control how safe is the code generated by native
+compilation, by customizing this user option.  It is also possible to
+control this at function granularity by using the new 'safety' parameter
+in the function's 'declare' form.
 
 ---
 ** New variable 'read-buffer-to-switch-current-buffer'.

diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 3e7674eeef6197fab78934f15ddeba20dd10cdfe..12b45f9f5b8836acb086271f52528907cf19c068 100644 (file)
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -138,11 +138,14 @@
   :group 'lisp)
 
 (defcustom compilation-safety 1
-  "Safety level for compilation.
+  "Safety level for generated compiled code.
 Possible values are:
-0 emitted code can misbehave or crash Emacs if function declarations are not
-correct.
-1 emitted code is generated in a safe matter even if function are miss-declared."
+  0 - emitted code can misbehave, even crash Emacs, if declarations of
+      functions do not correctly describe their actual behavior;
+  1 - emitted code is to be generated in a safe manner, even if functions
+      are mis-declared.
+
+This currently affects only code produced by native-compilation."
   :type 'integer
   :safe #'integerp
   :version "30.1")