bug#73626: 30.0.91; Type specifiers of functions

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

To reproduce:

  emacs -Q
  C-h f sort-lines RET

(That particular function is just an example, basically, any function
should do.)

Observe in the *Help* buffer:

  sort-lines is an autoloaded interactive byte-code-function in
  ‘sort.el’.

  (sort-lines REVERSE BEG END)

If sort.el was native-compiled, you will see this instead:

  sort-lines is an autoloaded interactive native-comp-function in
  ‘sort.el’.

  (sort-lines REVERSE BEG END)

So far so good, but in a long-running Emacs session I see this:

  sort-lines is an autoloaded interactive native-comp-function in
  ‘sort.el’.

  (sort-lines REVERSE BEG END)

  Inferred type: (function (t t t) t)  <<<<<<<<<<<<<<<<<<<<<<

and sometimes this:

  bobp is a primitive-function in ‘src/editfns.c’.

  (bobp)

  Declared type: (function nil boolean)  <<<<<<<<<<<<<<<<<<<<<

These Declared/Inferred type thingies are not documented anywhere,
AFAICT.  If one looks really hard, one can find in "Declare Form" the
description of "(ftype TYPE &optional FUNCTION)", but still nothing
about declared/inferred.  I see in help-fns.el:help-fns--signature
that we call comp-function-type-spec to get this information, and the
doc string of comp-function-type-spec says:

  Return the type specifier of FUNCTION.

But there are no matches for "type specifier" anywhere in the ELisp
manual, and comp-function-type-spec itself is not documented there.

Even after looking and finding all those pieces of the puzzle, the
overall picture is not clear.  The following is missing, and should be
documented in the ELisp manual:

 . what is the importance of inferred vs declared type
 . how to read the type specifiers, and in particular what do those
   "t" members mean, and more generally, which forms can appear in the
   car of the cons cell returned by comp-function-type-spec
 . why "C-h f" shows this information only for some functions and not
   for others, and what is the significance of that

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.

In GNU Emacs 30.0.91 (build 26, i686-pc-mingw32) of 2024-10-04 built on
 ELIZ-PC
Windowing system distributor 'Microsoft Corp.', version 10.0.22631
System Description: Microsoft Windows 10 Enterprise (v10.0.2009.22631.4169)

Configured using:
 'configure -C --prefix=/d/usr --with-wide-int
 --enable-checking=yes,glyphs --without-native-compilation 'CFLAGS=-O0
 -gdwarf-4 -g3''

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG LCMS2 LIBXML2 MODULES NOTIFY W32NOTIFY
PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS
TREE_SITTER WEBP XPM ZLIB

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1252

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  minibuffer-regexp-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow mail-extr emacsbug message mailcap yank-media puny dired
dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068
epg-config gnus-util time-date subr-x mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils shortdoc
text-property-search comp-common rx sort thingatpt help-fns radix-tree
help-mode cl-loaddefs cl-lib rmc iso-transl tooltip cconv eldoc paren
electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
touch-screen dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars
term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer nadvice seq simple cl-generic indonesian philippine
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite emoji-zwj charscript
charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads w32notify w32 lcms2 multi-tty move-toolbar make-network-process
emacs)

Memory information:
((conses 16 62131 14624) (symbols 48 7053 0) (strings 16 20202 2856)
 (string-bytes 1 391879) (vectors 16 10151)
 (vector-slots 8 115928 8847) (floats 8 79 4) (intervals 40 346 149)
 (buffers 896 11))

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

Ping!

> Cc: Andrea Corallo <acorallo@gnu.org>
> Date: Fri, 04 Oct 2024 15:25:50 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> To reproduce:
> 
>   emacs -Q
>   C-h f sort-lines RET
> 
> (That particular function is just an example, basically, any function
> should do.)
> 
> Observe in the *Help* buffer:
> 
>   sort-lines is an autoloaded interactive byte-code-function in
>   ‘sort.el’.
> 
>   (sort-lines REVERSE BEG END)
> 
> If sort.el was native-compiled, you will see this instead:
> 
>   sort-lines is an autoloaded interactive native-comp-function in
>   ‘sort.el’.
> 
>   (sort-lines REVERSE BEG END)
> 
> So far so good, but in a long-running Emacs session I see this:
> 
>   sort-lines is an autoloaded interactive native-comp-function in
>   ‘sort.el’.
> 
>   (sort-lines REVERSE BEG END)
> 
>   Inferred type: (function (t t t) t)  <<<<<<<<<<<<<<<<<<<<<<
> 
> and sometimes this:
> 
>   bobp is a primitive-function in ‘src/editfns.c’.
> 
>   (bobp)
> 
>   Declared type: (function nil boolean)  <<<<<<<<<<<<<<<<<<<<<
> 
> These Declared/Inferred type thingies are not documented anywhere,
> AFAICT.  If one looks really hard, one can find in "Declare Form" the
> description of "(ftype TYPE &optional FUNCTION)", but still nothing
> about declared/inferred.  I see in help-fns.el:help-fns--signature
> that we call comp-function-type-spec to get this information, and the
> doc string of comp-function-type-spec says:
> 
>   Return the type specifier of FUNCTION.
> 
> But there are no matches for "type specifier" anywhere in the ELisp
> manual, and comp-function-type-spec itself is not documented there.
> 
> Even after looking and finding all those pieces of the puzzle, the
> overall picture is not clear.  The following is missing, and should be
> documented in the ELisp manual:
> 
>  . what is the importance of inferred vs declared type
>  . how to read the type specifiers, and in particular what do those
>    "t" members mean, and more generally, which forms can appear in the
>    car of the cons cell returned by comp-function-type-spec
>  . why "C-h f" shows this information only for some functions and not
>    for others, and what is the significance of that
> 
> 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.
> 
> In GNU Emacs 30.0.91 (build 26, i686-pc-mingw32) of 2024-10-04 built on
>  ELIZ-PC
> Windowing system distributor 'Microsoft Corp.', version 10.0.22631
> System Description: Microsoft Windows 10 Enterprise (v10.0.2009.22631.4169)
> 
> Configured using:
>  'configure -C --prefix=/d/usr --with-wide-int
>  --enable-checking=yes,glyphs --without-native-compilation 'CFLAGS=-O0
>  -gdwarf-4 -g3''
> 
> Configured features:
> ACL GIF GMP GNUTLS HARFBUZZ JPEG LCMS2 LIBXML2 MODULES NOTIFY W32NOTIFY
> PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS
> TREE_SITTER WEBP XPM ZLIB
> 
> Important settings:
>   value of $LANG: ENU
>   locale-coding-system: cp1252
> 
> Major mode: Lisp Interaction
> 
> Minor modes in effect:
>   tooltip-mode: t
>   global-eldoc-mode: t
>   eldoc-mode: t
>   show-paren-mode: t
>   electric-indent-mode: t
>   mouse-wheel-mode: t
>   tool-bar-mode: t
>   menu-bar-mode: t
>   file-name-shadow-mode: t
>   global-font-lock-mode: t
>   font-lock-mode: t
>   blink-cursor-mode: t
>   minibuffer-regexp-mode: t
>   line-number-mode: t
>   indent-tabs-mode: t
>   transient-mark-mode: t
>   auto-composition-mode: t
>   auto-encryption-mode: t
>   auto-compression-mode: t
> 
> Load-path shadows:
> None found.
> 
> Features:
> (shadow mail-extr emacsbug message mailcap yank-media puny dired
> dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068
> epg-config gnus-util time-date subr-x mm-decode mm-bodies mm-encode
> mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
> rfc2045 ietf-drums mm-util mail-prsvr mail-utils shortdoc
> text-property-search comp-common rx sort thingatpt help-fns radix-tree
> help-mode cl-loaddefs cl-lib rmc iso-transl tooltip cconv eldoc paren
> electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
> touch-screen dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars
> term/common-win tool-bar dnd fontset image regexp-opt fringe
> tabulated-list replace newcomment text-mode lisp-mode prog-mode register
> page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
> scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
> frame minibuffer nadvice seq simple cl-generic indonesian philippine
> cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
> korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
> european ethiopic indian cyrillic chinese composite emoji-zwj charscript
> charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
> cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
> files window text-properties overlay sha1 md5 base64 format env
> code-pages mule custom widget keymap hashtable-print-readable backquote
> threads w32notify w32 lcms2 multi-tty move-toolbar make-network-process
> emacs)
> 
> Memory information:
> ((conses 16 62131 14624) (symbols 48 7053 0) (strings 16 20202 2856)
>  (string-bytes 1 391879) (vectors 16 10151)
>  (vector-slots 8 115928 8847) (floats 8 79 4) (intervals 40 346 149)
>  (buffers 896 11))
> 
> 
> 
> 

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

Hi Eli,

sorry for being late on this.

Eli Zaretskii <eliz@gnu.org> writes:

> To reproduce:
>
>   emacs -Q
>   C-h f sort-lines RET
>
> (That particular function is just an example, basically, any function
> should do.)
>
> Observe in the *Help* buffer:
>
>   sort-lines is an autoloaded interactive byte-code-function in
>   ‘sort.el’.
>
>   (sort-lines REVERSE BEG END)
>
> If sort.el was native-compiled, you will see this instead:
>
>   sort-lines is an autoloaded interactive native-comp-function in
>   ‘sort.el’.
>
>   (sort-lines REVERSE BEG END)
>
> So far so good, but in a long-running Emacs session I see this:
>
>   sort-lines is an autoloaded interactive native-comp-function in
>   ‘sort.el’.
>
>   (sort-lines REVERSE BEG END)
>
>   Inferred type: (function (t t t) t)  <<<<<<<<<<<<<<<<<<<<<<
>
> and sometimes this:
>
>   bobp is a primitive-function in ‘src/editfns.c’.
>
>   (bobp)
>
>   Declared type: (function nil boolean)  <<<<<<<<<<<<<<<<<<<<<
>
> These Declared/Inferred type thingies are not documented anywhere,
> AFAICT.  If one looks really hard, one can find in "Declare Form" the
> description of "(ftype TYPE &optional FUNCTION)", but still nothing
> about declared/inferred.  I see in help-fns.el:help-fns--signature
> that we call comp-function-type-spec to get this information, and the
> doc string of comp-function-type-spec says:
>
>   Return the type specifier of FUNCTION.
>
> But there are no matches for "type specifier" anywhere in the ELisp
> manual, and comp-function-type-spec itself is not documented there.
>
> Even after looking and finding all those pieces of the puzzle, the
> overall picture is not clear.  The following is missing, and should be
> documented in the ELisp manual:
>
>  . what is the importance of inferred vs declared type

The user get to know that the function type was computed by the compiler
or manually declared by the user.

>  . how to read the type specifiers,

The format is the same described for type declarations ((elisp)Top >
Functions > Declare Form).

I agree we should probably better document this somewhere else, probably
in Lisp Data Types?

> and in particular what do those "t" members mean,

t is a type documented (elisp)Top > Lisp Data Types > Type Hierarchy

> and more generally, which forms can appear in the
>    car of the cons cell returned by comp-function-type-spec

Hope I answered before.

>  . why "C-h f" shows this information only for some functions and not
>    for others, and what is the significance of that

C-h f does not show the inferred type if the functions has still to be
native compiled and loaded, the reason is simply that is the native
compiler computing the type.

> 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?
Otherwise where should we do it?

Thanks

  Andrea

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

> From: Andrea Corallo <acorallo@gnu.org>
> Cc: 73626@debbugs.gnu.org
> Date: Wed, 23 Oct 2024 18:29:06 -0400
> 
> Hi Eli,
> 
> sorry for being late on this.

No sweat.

> >  . what is the importance of inferred vs declared type
> 
> The user get to know that the function type was computed by the compiler
> or manually declared by the user.

And why is that important?

> >  . how to read the type specifiers,
> 
> The format is the same described for type declarations ((elisp)Top >
> Functions > Declare Form).

OK, but the relation of that to what we show in the *Help* buffers is
not obvious.

> I agree we should probably better document this somewhere else, probably
> in Lisp Data Types?

We need first mention this in "(emacs)Name Help", with a
cross-reference to wherever we describe that in the ELisp manual.  I
tend to think that the main place where this is described in ELisp
manual is somewhere in Lisp data Types, perhaps in Type Hierarchy.

> >  . why "C-h f" shows this information only for some functions and not
> >    for others, and what is the significance of that
> 
> C-h f does not show the inferred type if the functions has still to be
> native compiled and loaded, the reason is simply that is the native
> compiler computing the type.

This should also be documented in "Name Help", I think.

> > 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.

Thanks.

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrea Corallo <acorallo@gnu.org>
>> Cc: 73626@debbugs.gnu.org
>> Date: Wed, 23 Oct 2024 18:29:06 -0400
>> 
>> Hi Eli,
>> 
>> sorry for being late on this.
>
> No sweat.
>
>> >  . what is the importance of inferred vs declared type
>> 
>> The user get to know that the function type was computed by the compiler
>> or manually declared by the user.
>
> And why is that important?

I think might be informative for the user to know if the interface was
intentionally declared by the programmer or just inferred by the
compiler.  Of course this my evaluation is somehow subjective.

>> >  . how to read the type specifiers,
>> 
>> The format is the same described for type declarations ((elisp)Top >
>> Functions > Declare Form).
>
> OK, but the relation of that to what we show in the *Help* buffers is
> not obvious.

Agree.

>> I agree we should probably better document this somewhere else, probably
>> in Lisp Data Types?
>
> We need first mention this in "(emacs)Name Help", with a
> cross-reference to wherever we describe that in the ELisp manual.  I
> tend to think that the main place where this is described in ELisp
> manual is somewhere in Lisp data Types, perhaps in Type Hierarchy.
>
>> >  . why "C-h f" shows this information only for some functions and not
>> >    for others, and what is the significance of that
>> 
>> C-h f does not show the inferred type if the functions has still to be
>> native compiled and loaded, the reason is simply that is the native
>> compiler computing the type.
>
> This should also be documented in "Name Help", I think.
>
>> > 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.

  Andrea

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

> 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!

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

> 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?

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

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

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

[-- 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
 

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

> From: Andrea Corallo <acorallo@gnu.org>
> Cc: 73626@debbugs.gnu.org
> Date: Wed, 13 Nov 2024 19:27:52 -0500
> 
> 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?

Thanks, some minor comments below.

> 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

It would be good to have "function type specifier" in @dfn here, and
also have a @cindex entry for that.

> -@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

"Type Specifiers", in plural.  More importantly, using @ref in such a
way is not a good idea in Texinfo, it looks good only in the HTML
format.  For other formats, it is better to use the wordier

  @var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in
  the form...

> +@node Type Specifiers
> +@subsection Type Specifiers

Please add an index entry here

  @cindex type specifier

> +A type specifier is an expression that denotes a type. A type represents
                                                        ^^
Two spaces between sentences.

> +a set of possible values.  Type specifiers can be classified in
> +primitives and composites.

Since type specifiers are mostly (only?) used for functions, perhaps
the section should explicitly talk about "function type specifiers",
or at least mention "function" in several places in the text?

> +@subsubsection Primitive type specifiers.
> +Primitive types specifiers are the basic types (i.e. not composed by other

"i.e." needs a @: after it, since the period doesn't end a sentence.

> +Built-in primitive types (like @code{integer}, @code{float},
> +@code{string} etc) are listed in @xref{Type Hierarchy}.

@ref, not @xref.  The latter is only pertinent at the beginning of a
sentence, since it produces a capitalized "See".

> +@subsubsection Composite type specifiers.
> +Composite type specifiers allow the definition of complex types by
> +combining simpler types.

Instead of having @subsections here, I'd use a @table (with the
composite type specifiers being a nested @table inside that).  A
@table is easier to read and grasp, and also can save you typing,
since you can say

  @table @code

and avoid the need to use @code for each symbol.

> +@item @code{and}
> +
> +Similarly the @code{and} type specifier describes a type that satisfies
> +at all the given types.
   ^^
That "at" should be removed.

> +The @code{function} type specifier in the form @w{@code{(function
> +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument

The symbols you have in UPPER-CASE should be actually in @var and in
lower-case, as we always do with meta-syntactic arguments (i.e., with
symbols that stand for something other than themselves literally).

> +types and return type of a function. Argument types can be interleaved
                                      ^^
Two spaces.

> +The @code{integer} type specifier is used to define a subset of integers
> +by specifying a range. This allows to precisely control which integers
                        ^^
Likewise.

> +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

I wonder whether the description of the 'integer' type should be in
the "primitive types" part, since 'integer' is a primitive type, and
mentioned there?

A general note: I miss some higher-level background information here,
which would explain how these types are generated and how and for what
purposes they are used.  Such background doesn't have to be too
detailed or too technical, but it is important to provide the
rationale for this feature.

In addition, if there's a value or an advantage to have type
information about functions, this section should explain the
advantages and encourage Lisp programmers to use the relevant
facilities (AFAIU, the 'declare' form; is there anything else?) to
provide that information.

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrea Corallo <acorallo@gnu.org>
>> Cc: 73626@debbugs.gnu.org
>> Date: Wed, 13 Nov 2024 19:27:52 -0500
>>
>> 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?
>
> Thanks, some minor comments below.
>
>> 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
>
> It would be good to have "function type specifier" in @dfn here, and
> also have a @cindex entry for that.
>
>> -@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
>
> "Type Specifiers", in plural.  More importantly, using @ref in such a
> way is not a good idea in Texinfo, it looks good only in the HTML
> format.  For other formats, it is better to use the wordier
>
>   @var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in
>   the form...
>
>> +@node Type Specifiers
>> +@subsection Type Specifiers
>
> Please add an index entry here
>
>   @cindex type specifier

>> +A type specifier is an expression that denotes a type. A type represents
>                                                         ^^
> Two spaces between sentences.
>
>> +a set of possible values.  Type specifiers can be classified in
>> +primitives and composites.
>
> Since type specifiers are mostly (only?) used for functions, perhaps
> the section should explicitly talk about "function type specifiers",
> or at least mention "function" in several places in the text?

They are also usable under `cl-the', 'cl-defstruct' and probably few
other cl facilities.  (BTW I'd like to have 'cl-the' or a new 'the'
wired to the compile machinery for the future).

>> +@subsubsection Primitive type specifiers.
>> +Primitive types specifiers are the basic types (i.e. not composed by other
>
> "i.e." needs a @: after it, since the period doesn't end a sentence.
>
>> +Built-in primitive types (like @code{integer}, @code{float},
>> +@code{string} etc) are listed in @xref{Type Hierarchy}.
>
> @ref, not @xref.  The latter is only pertinent at the beginning of a
> sentence, since it produces a capitalized "See".
>
>> +@subsubsection Composite type specifiers.
>> +Composite type specifiers allow the definition of complex types by
>> +combining simpler types.
>
> Instead of having @subsections here, I'd use a @table (with the
> composite type specifiers being a nested @table inside that).
>
> A
> @table is easier to read and grasp, and also can save you typing,
> since you can say
>
>   @table @code
>
> and avoid the need to use @code for each symbol.
>
>> +@item @code{and}
>> +
>> +Similarly the @code{and} type specifier describes a type that satisfies
>> +at all the given types.
>    ^^
> That "at" should be removed.
>
>> +The @code{function} type specifier in the form @w{@code{(function
>> +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument
>
> The symbols you have in UPPER-CASE should be actually in @var and in
> lower-case, as we always do with meta-syntactic arguments (i.e., with
> symbols that stand for something other than themselves literally).
>
>> +types and return type of a function. Argument types can be interleaved
>                                       ^^
> Two spaces.
>
>> +The @code{integer} type specifier is used to define a subset of integers
>> +by specifying a range. This allows to precisely control which integers
>                         ^^
> Likewise.
>
>> +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
>
> I wonder whether the description of the 'integer' type should be in
> the "primitive types" part, since 'integer' is a primitive type, and
> mentioned there?

'integer' is a primitive type when used alone, but is a compound one if
used as (integer min max).  I think I've clarified that.

> A general note: I miss some higher-level background information here,
> which would explain how these types are generated and how and for what
> purposes they are used.  Such background doesn't have to be too
> detailed or too technical, but it is important to provide the
> rationale for this feature.

Okay I tried to add some brief context.

Attached the latest version where I tried to implement the suggestions.

Thanks!

  Andrea


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

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index f15b4c5e89d..079ea76156f 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -322,6 +322,15 @@ Name Help
 yet further information is often reachable by clicking or typing
 @key{RET} on emphasized parts of the text.
 
+@cindex function type specifier
+
+The function type, if known, is expressed with a @dfn{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..bb548441cbc 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2733,10 +2733,10 @@ 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
-(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 (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{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 @@ 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,92 @@ Type Descriptors
 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
 

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

> From: Andrea Corallo <acorallo@gnu.org>
> Cc: 73626@debbugs.gnu.org
> Date: Tue, 19 Nov 2024 04:55:25 -0500
> 
> Attached the latest version where I tried to implement the suggestions.

> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the
> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}.

ARG-1-TYPE etc. should be in @var and lower-case.

Otherwise, this can go in, I think.

Thanks.

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrea Corallo <acorallo@gnu.org>
>> Cc: 73626@debbugs.gnu.org
>> Date: Tue, 19 Nov 2024 04:55:25 -0500
>> 
>> Attached the latest version where I tried to implement the suggestions.
>
>> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the
>> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}.
>
> ARG-1-TYPE etc. should be in @var and lower-case.

👍

> Otherwise, this can go in, I think.

emacs-30 right?

  Andrea

bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii]

> From: Andrea Corallo <acorallo@gnu.org>
> Cc: 73626@debbugs.gnu.org
> Date: Thu, 21 Nov 2024 08:15:00 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Andrea Corallo <acorallo@gnu.org>
> >> Cc: 73626@debbugs.gnu.org
> >> Date: Tue, 19 Nov 2024 04:55:25 -0500
> >> 
> >> Attached the latest version where I tried to implement the suggestions.
> >
> >> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the
> >> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}.
> >
> > ARG-1-TYPE etc. should be in @var and lower-case.
> 
> 👍
> 
> > Otherwise, this can go in, I think.
> 
> emacs-30 right?

Yes, please.

bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrea Corallo <acorallo@gnu.org>
>> Cc: 73626@debbugs.gnu.org
>> Date: Thu, 21 Nov 2024 08:15:00 -0500
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Andrea Corallo <acorallo@gnu.org>
>> >> Cc: 73626@debbugs.gnu.org
>> >> Date: Tue, 19 Nov 2024 04:55:25 -0500
>> >> 
>> >> Attached the latest version where I tried to implement the suggestions.
>> >
>> >> +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the
>> >> +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}.
>> >
>> > ARG-1-TYPE etc. should be in @var and lower-case.
>> 
>> 👍
>> 
>> > Otherwise, this can go in, I think.
>> 
>> emacs-30 right?
>
> Yes, please.

That's done thanks, closing

  Andrea

bug#73626: 30.0.91; Type specifiers of functions

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > -@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)}}.

Please don't use a cross-reference to stand in for a nominal.  It
isn't grammatically coherent, and I think it will look completely
wrong in some output formats.

The right thing to use here is this:

  type specifier (@pxrer{Type Specifier})


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)