diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index f15b4c5e89d..0f85ff0c832 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -322,6 +322,13 @@ Name Help yet further information is often reachable by clicking or typing @key{RET} on emphasized parts of the text. +The function type, if known, is expressed with a function type specifier +(@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference Manual}), it +will be specified if the type was manually declared by the programmer or +inferred by the compiler. Note that function type inference works only +when native compilation is enabled (@pxref{native compilation,,, elisp, +The Emacs Lisp Reference Manual}). + @vindex help-enable-symbol-autoload If you request help for an autoloaded function whose @code{autoload} form (@pxref{Autoload,,, elisp, The Emacs Lisp Reference Manual}) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index bf80a21ee9f..c6953cdd25a 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2733,7 +2733,7 @@ Declare Form generation and for deriving more precisely the type of other functions without type declaration. -@var{type} is a type specifier in the form @w{@code{(function +@var{type} is a @ref{Type Specifier} in the form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. Argument types can be interleaved with symbols @code{&optional} and @code{&rest} to match the function's arguments (@pxref{Argument List}). diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 34ea7cf4996..e402eed9437 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -247,6 +247,7 @@ Programming Types * Closure Type:: A function written in Lisp. * Record Type:: Compound objects with programmer-defined types. * Type Descriptors:: Objects holding information about types. +* Type Specifiers:: Expressions which describe types. * Autoload Type:: A type used for automatically loading seldom-used functions. * Finalizer Type:: Runs code when no longer reachable. @@ -1499,6 +1500,99 @@ Type Descriptors An example of a type descriptor is any instance of @code{cl-structure-class}. +@node Type Specifiers +@subsection Type Specifiers + +A type specifier is an expression that denotes a type. A type represents +a set of possible values. Type specifiers can be classified in +primitives and composites. + +@subsubsection Primitive type specifiers. +Primitive types specifiers are the basic types (i.e. not composed by other +type specifiers). + +Built-in primitive types (like @code{integer}, @code{float}, +@code{string} etc) are listed in @xref{Type Hierarchy}. + +@subsubsection Composite type specifiers. +Composite type specifiers allow the definition of complex types by +combining simpler types. + +List of composite composite type specifiers: + +@itemize @bullet +@item @code{or} + +The @code{or} type specifier describes a type that satisfies at least one of +the given types. +@example +(or integer float) +@end example + +@item @code{and} + +Similarly the @code{and} type specifier describes a type that satisfies +at all the given types. + +@item @code{not} + +The @code{not} type specifier defines any type except the specified one. +@example +(not number) +@end example + +@item @code{member} + +The @code{member} type specifier allows to specify a type that includes +only the explicitly listed values. +@example +(member foo bar) +@end example + +@item @code{function} + +The @code{function} type specifier in the form @w{@code{(function +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument +types and 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 following is to represent a function with: a first parameter of type +@code{symbol}, a second optional parameter of type @code{float} and +returning an @code{integer}: +@example +(function (symbol &optional float) integer) +@end example + +@item @code{integer} + +The @code{integer} type specifier is used to define a subset of integers +by specifying a range. This allows to precisely control which integers +are valid for a given type. + +The general form is: +@example +(integer lower-bound upper-bound) +@end example +Where @code{lower-bound} is the minimum integer value in the range and +@code{upper-bound} the maximum. It is possible to use @code{*} to +indicate no lower or uper limit. + +The following represents all integers from -10 to 10. +@example +(integer -10 10) +@end example + +The following represents 10. +@example +(integer 10 10) +@end example + +The following represents all integers from negative infinity to 10. +@example +(integer * 10) +@end example + @node Autoload Type @subsection Autoload Type