From 3df7d7011c62257a0b8c197e1e54e1ef40700ffc Mon Sep 17 00:00:00 2001
From: Andrea Corallo <acorallo@gnu.org>
Date: Thu, 2 May 2024 16:38:14 +0200
Subject: [PATCH] * doc/lispref/functions.texi (Declare Form): Improve again
 declare type.

(cherry picked from commit 02690d95f9e47163ecca9b26a01270215727cd69)
---
 doc/lispref/functions.texi | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 3aa4fc9a457..d88f5d05339 100644
--- 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
-- 
2.39.5