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 function type declaration
@cindex inferred type of function @cindex inferred type of function
@item (ftype @var{type} &optional @var{function}) @item (ftype @var{type} &optional @var{function})
Declare @var{type} to be the type of this function. This is used for Declare @var{type} to be the type of this function. This type is used
documentation by @code{describe-function}. Also it can be used by the by @code{describe-function} for documentation, and by the native
native compiler (@pxref{Native Compilation}) for improving code compiler (@pxref{Native Compilation}) for optimizing code generation and
generation and for deriving more precisely the type of other functions inferring types. Incorrect type declarations may cause crashes in
without type declaration. Functions that have such type declarations natively compiled code (see below). Functions with type declarations
will be shown by @kbd{C-h C-f} as having a @dfn{declared type} (as are shown by @kbd{C-h C-f} as having a @dfn{declared type}, as opposed
opposed to @dfn{inferred type} of functions without declaration). 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}) form @w{@code{(function (@var{arg-1-type} @dots{} @var{arg-n-type})
RETURN-TYPE)}}. Argument types can be interleaved with symbols RETURN-TYPE)}}. Argument types can be interleaved with @code{&optional}
@code{&optional} and @code{&rest} to match the function's arguments and @code{&rest} to reflect the function's calling convention
(@pxref{Argument List}). (@pxref{Argument List}).
@var{function} if present should be the name of function being defined. @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 Here's an example of using @code{ftype} inside @code{declare} to define
a function @code{positive-p} that takes an argument of type @var{number} a function @code{positive-p}, which takes an argument of type
and return a @var{boolean}: @var{number} and returns a @var{boolean}:
@lisp @lisp
@group @group
@ -2758,9 +2758,9 @@ and return a @var{boolean}:
@end group @end group
@end lisp @end lisp
Similarly this declares a function @code{cons-or-number} that: expects a Similarly, this defines a function @code{cons-or-number} that takes a
first argument being a @var{cons} or a @var{number}, a second optional first argument of type @var{cons} or a @var{number}, a second optional
argument of type @var{string} and return one of the symbols argument of type @var{string}, and returns one of the symbols
@code{is-cons} or @code{is-number}: @code{is-cons} or @code{is-number}:
@lisp @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}). For description of additional types, see @ref{Lisp Data Types}).
Declaring a function with an incorrect type produces undefined behavior Declaring a function with an incorrect type causes undefined behavior.
and could lead to unexpected results or might even crash Emacs when If such a function is natively compiled with @code{compilation-safety}
natively-compiled code is loaded, if it was compiled with set to zero (@pxref{compilation-safety}), this may result in incorrect
@code{compilation-safety} level of zero (@pxref{compilation-safety}). execution or even Emacs crashing when the compiled code is loaded.
Note also that when redefining (or advising) a type-declared function, Redefining or advising a type-declared function must preserve the
the replacement should respect the original signature to avoid such original signature to avoid these issues.
undefined behavior.
@item no-font-lock-keyword @item no-font-lock-keyword
This is valid for macros only. Macros with this declaration are 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 represents a set of possible values. Type specifiers can be classified
into primitive types and compound types. into primitive types and compound types.
Type specifiers are in use for several purposes, including: documenting Type specifiers are used for several purposes, including: documenting
function interfaces through declaration (@pxref{Declare Form}), function interfaces through declarations (@pxref{Declare Form}),
specifying structure slot values (@pxref{Structures,,, cl, Common Lisp specifying structure slot types (@pxref{Structures,,, cl, Common Lisp
Extensions for GNU Emacs Lisp}), type-checking through @code{cl-the} Extensions for GNU Emacs Lisp}), performing type checks with
(@pxref{Declarations,,, cl, Common Lisp Extensions for GNU Emacs Lisp}), @code{cl-the} (@pxref{Declarations,,, cl, Common Lisp Extensions for GNU
and others. Emacs Lisp}), and aiding the native compiler (@pxref{Native
Compilation}) in optimizing code generation and inferring function
signatures.
@table @asis @table @asis
@item Primitive type specifiers @item Primitive type specifiers