* doc/lispref/functions.texi (Declare Form): Improve again declare type.

(cherry picked from commit 02690d95f9e47163ecca9b26a01270215727cd69)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 3aa4fc9a457d0d325af00c4e5e44d26fea7a94bd..d88f5d05339a1f026a82f186b05825c7e18315d0 100644 (file)
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2712,31 +2712,34 @@ instead of native code for the function.
 @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
-native compiler (@pxref{Native-Compilation}) for improving code
+native compiler (@pxref{Native Compilation}) for improving code
 generation and for deriving more precisely the type of other functions
 without type declaration.
 
-@var{type} is a type specifier in the form @code{(function (ARG-1-TYPE
-... ARG-N-TYPE) RETURN-TYPE)}.  Argument types can be interleaved with
-symbols @code{&optional} and @code{&rest} to match the @pxref{Argument
-List} of the function.
+@var{type} is a type specifier in the form @w{@code{(function
+(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}.  Argument types can be
+interleaved with symbols @code{&optional} and @code{&rest} to match the
+function's arguments (@pxref{Argument List}).
 
 Here's an example of using @code{type} inside @code{declare} to declare
 a function @code{positive-p} that takes an argument of type @var{number}
 and return a @var{boolean}:
 
+@group
 @lisp
 (defun positive-p (x)
   (declare (type (function (number) boolean)))
   (when (> x 0)
     t))
 @end lisp
+@end group
 
 Similarly this declares a function @code{cons-or-number} that: expects a
 first argument being a @var{cons} or a @var{number}, a second optional
 argument of type @var{string} and return one of the symbols
 @code{is-cons} or @code{is-number}:
 
+@group
 @lisp
 (defun cons-or-number (x &optional err-msg)
   (declare (type (function ((or cons number) &optional string)
@@ -2747,14 +2750,16 @@ argument of type @var{string} and return one of the symbols
        'is-number
       (error (or err-msg "Unexpected input")))))
 @end lisp
+@end group
 
-More types are described in @pxref{Lisp Data Types}.
+More types are described in the Lisp Data Types chapter (@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.  Note
-also that when redefining (or advising) a type declared function the
-replacement should respect the original signature to avoid 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.
 
 @item no-font-lock-keyword
 This is valid for macros only.  Macros with this declaration are