bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo <acorallo@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 1370 bytes --]

Andrea Corallo <acorallo@gnu.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Cc: 73626@debbugs.gnu.org
>>> Date: Fri, 25 Oct 2024 13:19:41 +0300
>>> From: Eli Zaretskii <eliz@gnu.org>
>>> 
>>> > From: Andrea Corallo <acorallo@gnu.org>
>>> > Cc: 73626@debbugs.gnu.org
>>> > Date: Fri, 25 Oct 2024 05:35:30 -0400
>>> > 
>>> > Eli Zaretskii <eliz@gnu.org> writes:
>>> > 
>>> > >> > Bottom line: we decided that this information is important enough to
>>> > >> > show it in the *Help* buffer, so we should explain its arcane parts to
>>> > >> > make them useful.
>>> > >> 
>>> > >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that?
>>> > >
>>> > > Yes, I think so.
>>> > 
>>> > Ok gonna work on this.
>>> 
>>> Thanks!
>>
>> Did you have a chance to work on this?
>
> Not so far sorry, it's on top of my todo list tho.
>
>   Andrea

Okay this is what I'm working on.  I felt the need to add a more general
'(elisp)Type Specifiers' node as this was never documented and I think
deserves its own space.

I referenced it from '(emacs)Name Help' where I mentioned we report
function type specifiers.  Also I could reference it from '(elisp)
Declare Form' so that the concept of type specifier (there already
mentioned) is explained.

There are some mentions of type specifiers in cl.texi which I guess I'll
add some xref as well.

WDYT?

  Andrea


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: ts.patch --]
[-- Type: text/x-diff, Size: 4908 bytes --]

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