bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii <eliz@gnu.org>]

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