bug#73626: 30.0.91; Type specifiers of functions

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