scratch/comp-safety2 bf3a49d56fc 3/4: Add some 'compilation-safety' documentation

[Andrea Corallo]

branch: scratch/comp-safety2
commit bf3a49d56fc4cdc92be50c79f41cfd5d97ff5dc6
Author: Andrea Corallo <acorallo@gnu.org>
Commit: Andrea Corallo <acorallo@gnu.org>

    Add some 'compilation-safety' documentation
    
    * lisp/emacs-lisp/bytecomp.el (compilation-safety): Better doc.
    * lisp/emacs-lisp/comp.el (comp--type-relax-alist): Likewise.
    * doc/lispref/functions.texi (Declare Form): Add 'safety'.
    * doc/lispref/compile.texi (Native-Compilation Variables): Add
    'compilation-safety'.
---
 doc/lispref/compile.texi    | 18 ++++++++++++++++++
 doc/lispref/functions.texi  | 13 ++++++++++---
 lisp/emacs-lisp/bytecomp.el |  5 ++++-
 3 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 19451f31740..f8f1242586e 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -987,6 +987,24 @@ form, @pxref{Declare Form}.)
 The default value is 2.
 @end defopt
 
+@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:
+
+@table @asis
+@item 0
+Emitted code can misbehave or crash Emacs if function declarations are
+not correct and the function is native compiled.
+@item 1
+Emitted code is generated in a safe matter even if function are
+miss-declared."
+@end table
+
+This can be controlled at function granularity as well by using the
+@code{safety} @code{declare} form, @pxref{Declare Form}.
+@end defopt
+
 @defopt native-comp-debug
 This variable specifies the level of debugging information produced by
 native-compilation.  Its value should be a number between zero and 3,
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index a77bf6e233d..9d4ecd8da25 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2709,6 +2709,12 @@ 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 (safety @var{n})
+Specify the value of @code{compilation-safety} in effect for this
+function.  This allows function-level control of the safety level used
+for the code emitted for the function (@pxref{Native-Compilation
+Variables}).
+
 @item (type @var{type})
 Declare @var{type} to be the type of this function.  This is used for
 documentation by @code{describe-function}.  Also it can be used by the
@@ -2756,9 +2762,10 @@ 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.  Note also that when redefining (or
-advising) a type declared function the replacement should respect the
-original signature to avoid undefined behavior.
+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
+undefined behavior.
 
 @item no-font-lock-keyword
 This is valid for macros only.  Macros with this declaration are
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 732a1629177..5d13ad69284 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -138,7 +138,10 @@
   :group 'lisp)
 
 (defcustom compilation-safety 1
-  "Safety level."
+  "Safety level for compilation.
+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."
   :type 'integer
   :safe #'integerp
   :version "30.1")