procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Improve type specifier documentation

Browse source 
* 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.
This commit is contained in:
Stefan Kangas 2025-03-25 23:16:11 +01:00
parent 6a3e2b88d2
commit b3881ac443
2 changed files with 30 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
doc/lispref/functions.texi
View file

@ -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).
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}) in the
@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

14
doc/lispref/objects.texi
View file

@ -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