diff options
Diffstat (limited to 'doc/lispref/functions.texi')
| -rw-r--r-- | doc/lispref/functions.texi | 47 |
1 files changed, 23 insertions, 24 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 |