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!