bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo <acorallo@gnu.org>]

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