bug#73626: 30.0.91; Type specifiers of functions

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrea Corallo <acorallo@gnu.org>
> Cc: 73626@debbugs.gnu.org
> Date: Wed, 13 Nov 2024 19:27:52 -0500
> 
> Okay this is what I'm working on.  I felt the need to add a more general
> '(elisp)Type Specifiers' node as this was never documented and I think
> deserves its own space.
> 
> I referenced it from '(emacs)Name Help' where I mentioned we report
> function type specifiers.  Also I could reference it from '(elisp)
> Declare Form' so that the concept of type specifier (there already
> mentioned) is explained.
> 
> There are some mentions of type specifiers in cl.texi which I guess I'll
> add some xref as well.
> 
> WDYT?

Thanks, some minor comments below.

> diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
> index f15b4c5e89d..0f85ff0c832 100644
> --- a/doc/emacs/help.texi
> +++ b/doc/emacs/help.texi
> @@ -322,6 +322,13 @@ Name Help
>  yet further information is often reachable by clicking or typing
>  @key{RET} on emphasized parts of the text.
>  
> +The function type, if known, is expressed with a function type specifier
> +(@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference Manual}), it

It would be good to have "function type specifier" in @dfn here, and
also have a @cindex entry for that.

> -@var{type} is a type specifier in the form @w{@code{(function
> +@var{type} is a @ref{Type Specifier} in the form @w{@code{(function

"Type Specifiers", in plural.  More importantly, using @ref in such a
way is not a good idea in Texinfo, it looks good only in the HTML
format.  For other formats, it is better to use the wordier

  @var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in
  the form...

> +@node Type Specifiers
> +@subsection Type Specifiers

Please add an index entry here

  @cindex type specifier

> +A type specifier is an expression that denotes a type. A type represents
                                                        ^^
Two spaces between sentences.

> +a set of possible values.  Type specifiers can be classified in
> +primitives and composites.

Since type specifiers are mostly (only?) used for functions, perhaps
the section should explicitly talk about "function type specifiers",
or at least mention "function" in several places in the text?

> +@subsubsection Primitive type specifiers.
> +Primitive types specifiers are the basic types (i.e. not composed by other

"i.e." needs a @: after it, since the period doesn't end a sentence.

> +Built-in primitive types (like @code{integer}, @code{float},
> +@code{string} etc) are listed in @xref{Type Hierarchy}.

@ref, not @xref.  The latter is only pertinent at the beginning of a
sentence, since it produces a capitalized "See".

> +@subsubsection Composite type specifiers.
> +Composite type specifiers allow the definition of complex types by
> +combining simpler types.

Instead of having @subsections here, I'd use a @table (with the
composite type specifiers being a nested @table inside that).  A
@table is easier to read and grasp, and also can save you typing,
since you can say

  @table @code

and avoid the need to use @code for each symbol.

> +@item @code{and}
> +
> +Similarly the @code{and} type specifier describes a type that satisfies
> +at all the given types.
   ^^
That "at" should be removed.

> +The @code{function} type specifier in the form @w{@code{(function
> +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} used to describe the argument

The symbols you have in UPPER-CASE should be actually in @var and in
lower-case, as we always do with meta-syntactic arguments (i.e., with
symbols that stand for something other than themselves literally).

> +types and return type of a function. Argument types can be interleaved
                                      ^^
Two spaces.

> +The @code{integer} type specifier is used to define a subset of integers
> +by specifying a range. This allows to precisely control which integers
                        ^^
Likewise.

> +are valid for a given type.
> +
> +The general form is:
> +@example
> +(integer lower-bound upper-bound)
> +@end example
> +Where @code{lower-bound} is the minimum integer value in the range and
> +@code{upper-bound} the maximum.  It is possible to use @code{*} to
> +indicate no lower or uper limit.
> +
> +The following represents all integers from -10 to 10.
> +@example
> +(integer -10 10)
> +@end example
> +
> +The following represents 10.
> +@example
> +(integer 10 10)
> +@end example
> +
> +The following represents all integers from negative infinity to 10.
> +@example
> +(integer * 10)
> +@end example

I wonder whether the description of the 'integer' type should be in
the "primitive types" part, since 'integer' is a primitive type, and
mentioned there?

A general note: I miss some higher-level background information here,
which would explain how these types are generated and how and for what
purposes they are used.  Such background doesn't have to be too
detailed or too technical, but it is important to provide the
rationale for this feature.

In addition, if there's a value or an advantage to have type
information about functions, this section should explain the
advantages and encourage Lisp programmers to use the relevant
facilities (AFAIU, the 'declare' form; is there anything else?) to
provide that information.