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

4 files changed, 27 insertions, 19 deletions

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index f8f1242586e..9f93fb4a981 100644
--- 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 9d4ecd8da25..deca99960c7 100644
--- 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 5f131386a43..5ecc385fa5b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1986,9 +1986,11 @@ unibyte string.
 
 * 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 types 'closure' and 'interpreted-function'.
 'interpreted-function' is the new type used for interpreted functions,
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 3e7674eeef6..12b45f9f5b8 100644
--- 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")