; Introduce type specifiers to the elisp manual (bug#73626)

* doc/lispref/objects.texi (Programming Types): Add 'Type Specifiers' entry.
(Type Specifiers): Add node.
* doc/lispref/functions.texi (Declare Form): Add 'Type Specifiers'
reference.

2 files changed, 92 insertions, 4 deletions

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 7fb9fb37c0a..4ffa3d7ead4 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2733,10 +2733,11 @@ native compiler (@pxref{Native Compilation}) for improving code
 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
-(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}).
+@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the
+form @w{@code{(function (@var{arg-1-type} ... @var{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}).
 
 @var{function} if present should be the name of function being defined.
 
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 34ea7cf4996..d847f438e0f 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -247,6 +247,7 @@ latter are unique to Emacs Lisp.
 * 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,92 @@ free for use by Lisp extensions.
 An example of a type descriptor is any instance of
 @code{cl-structure-class}.
 
+@node Type Specifiers
+@subsection Type Specifiers
+@cindex type specifier
+
+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 compounds.
+
+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.
+
+@table @asis
+@item 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 @ref{Type Hierarchy}.
+
+@item Compound type specifiers
+Compound types serve the purpose of defining more complex or precise
+type specifications by combining or modifying simpler types.
+
+List of compound type specifiers:
+
+@table @code
+@item (or @var{type-1} .. @var{type-n})
+The @code{or} type specifier describes a type that satisfies at least
+one of the given types.
+
+@item (and @var{type-1} .. @var{type-n})
+Similarly the @code{and} type specifier describes a type that satisfies
+all the given types.
+
+@item (not @var{type})
+The @code{not} type specifier defines any type except the specified one.
+
+@item (member @var{value-1} .. @var{value-n})
+The @code{member} type specifier allows to specify a type that includes
+only the explicitly listed values.
+
+@item (function (@var{arg-1-type} ... @var{arg-n-type}) @var{return-type})
+The @code{function} type specifier is 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 (integer @var{lower-bound} @var{upper-bound})
+
+@code{integer} can be used as well as a compound type specifier to
+define a subset of integers by specifying a range.  This allows to
+precisely control which integers are valid for a given type.
+
+@var{lower-bound} is the minimum integer value in the range and
+@var{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
+
+@end table
+@end table
+
 @node Autoload Type
 @subsection Autoload Type