From 6a3e2b88d26db4f703c566cf9b508f8c83ea8850 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 25 Mar 2025 14:37:17 +0200 Subject: [PATCH 1/3] ; Improve documentation of "function types" * doc/lispref/functions.texi (Declare Form): * doc/lispref/objects.texi (Type Specifiers): Improve wording and indexing. --- doc/lispref/functions.texi | 5 ++++- doc/lispref/objects.texi | 6 +++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 1da5208065e..824db5a0ec8 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2727,12 +2727,15 @@ for the code emitted for the function (@pxref{Native-Compilation 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. +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 form @w{@code{(function (@var{arg-1-type} @dots{} @var{arg-n-type}) diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 630765213a2..264a780f93d 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1552,9 +1552,9 @@ types and the return type of a function. Argument types can be interleaved with symbols @code{&optional} and @code{&rest} to match the function's arguments (@pxref{Argument List}). -The type specifier represent a function whose first parameter is of type -@code{symbol}, the second optional parameter is of type @code{float}, -and which returns an @code{integer}: +The following type specifier represents a function whose first parameter +is of type @code{symbol}, the second optional parameter is of type +@code{float}, and which returns an @code{integer}: @example (function (symbol &optional float) integer) From b3881ac443f2ab279aba3d9687792c71d97554d0 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Tue, 25 Mar 2025 23:16:11 +0100 Subject: [PATCH 2/3] ; 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. --- doc/lispref/functions.texi | 45 +++++++++++++++++++------------------- doc/lispref/objects.texi | 14 +++++++----- 2 files changed, 30 insertions(+), 29 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). +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 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 From 9a07d64f5c734f08baa741d763640943a7b407e7 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Wed, 26 Mar 2025 01:03:06 +0100 Subject: [PATCH 3/3] ; Minor update in ack.texi MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/emacs/ack.texi (Acknowledgments): Mention eglot in entry for João Távora. --- doc/emacs/ack.texi | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 542d54fe717..81784d4989b 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -1302,8 +1302,9 @@ Tibor Šimko and Milan Zamazal wrote @file{slovak.el}, support for editing text in Slovak language. @item -João Távora wrote many improvements for @file{flymake.el}, an -on-the-fly syntax-checking package. +João Távora wrote many improvements for @file{flymake.el}, an on-the-fly +syntax-checking package. He also wrote @file{eglot.el}, a language +server protocol (LSP) client that was added in Emacs 29. @item Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through