bug#73626: 30.0.91; Type specifiers of functions

[Andrea Corallo <acorallo@gnu.org>]

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