; Improve type specifier documentation

* doc/lispref/functions.texi (Declare Form): Clarify wording for
precision and consistency; note consequences of incorrect declarations.
* doc/lispref/objects.texi (Type Specifiers): Mention use by the native
compiler; tighten wording.

2 files changed, 31 insertions, 30 deletions

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 824db5a0ec8..180d6a41698 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2729,25 +2729,25 @@ Variables}).
 @cindex function type declaration
 @cindex inferred type of function
 @item (ftype @var{type} &optional @var{function})
-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
-generation and for deriving more precisely the type of other functions
-without type declaration.  Functions that have such type declarations
-will be shown by @kbd{C-h C-f} as having a @dfn{declared type} (as
-opposed to @dfn{inferred type} of functions without declaration).
-
-@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the
+Declare @var{type} to be the type of this function.  This type is used
+by @code{describe-function} for documentation, and by the native
+compiler (@pxref{Native Compilation}) for optimizing code generation and
+inferring types.  Incorrect type declarations may cause crashes in
+natively compiled code (see below).  Functions with type declarations
+are shown by @kbd{C-h C-f} as having a @dfn{declared type}, as opposed
+to an @dfn{inferred type} for functions without them.
+
+@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) of the
 form @w{@code{(function (@var{arg-1-type} @dots{} @var{arg-n-type})
-RETURN-TYPE)}}.  Argument types can be interleaved with symbols
-@code{&optional} and @code{&rest} to match the function's arguments
+RETURN-TYPE)}}.  Argument types can be interleaved with @code{&optional}
+and @code{&rest} to reflect the function's calling convention
 (@pxref{Argument List}).
 
 @var{function} if present should be the name of function being defined.
 
-Here's an example of using @code{ftype} inside @code{declare} to declare
-a function @code{positive-p} that takes an argument of type @var{number}
-and return a @var{boolean}:
+Here's an example of using @code{ftype} inside @code{declare} to define
+a function @code{positive-p}, which takes an argument of type
+@var{number} and returns a @var{boolean}:
 
 @lisp
 @group
@@ -2758,9 +2758,9 @@ and return a @var{boolean}:
 @end group
 @end lisp
 
-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
+Similarly, this defines a function @code{cons-or-number} that takes a
+first argument of type @var{cons} or a @var{number}, a second optional
+argument of type @var{string}, and returns one of the symbols
 @code{is-cons} or @code{is-number}:
 
 @lisp
@@ -2778,13 +2778,12 @@ 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
-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.
+Declaring a function with an incorrect type causes undefined behavior.
+If such a function is natively compiled with @code{compilation-safety}
+set to zero (@pxref{compilation-safety}), this may result in incorrect
+execution or even Emacs crashing when the compiled code is loaded.
+Redefining or advising a type-declared function must preserve the
+original signature to avoid these issues.
 
 @item no-font-lock-keyword
 This is valid for macros only.  Macros with this declaration are
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 264a780f93d..a752a2125b4 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1508,12 +1508,14 @@ A type specifier is an expression that denotes a type.  A type
 represents a set of possible values.  Type specifiers can be classified
 into primitive types and compound types.
 
-Type specifiers are in use for several purposes, including: documenting
-function interfaces through declaration (@pxref{Declare Form}),
-specifying structure slot values (@pxref{Structures,,, cl, Common Lisp
-Extensions for GNU Emacs Lisp}), type-checking through @code{cl-the}
-(@pxref{Declarations,,, cl, Common Lisp Extensions for GNU Emacs Lisp}),
-and others.
+Type specifiers are used for several purposes, including: documenting
+function interfaces through declarations (@pxref{Declare Form}),
+specifying structure slot types (@pxref{Structures,,, cl, Common Lisp
+Extensions for GNU Emacs Lisp}), performing type checks with
+@code{cl-the} (@pxref{Declarations,,, cl, Common Lisp Extensions for GNU
+Emacs Lisp}), and aiding the native compiler (@pxref{Native
+Compilation}) in optimizing code generation and inferring function
+signatures.
 
 @table @asis
 @item Primitive type specifiers