Re: Declaring Lisp function types

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrea Corallo <acorallo@gnu.org>
> Cc: emacs-devel@gnu.org,  stefankangas@gmail.com,  adam@alphapapa.net,
>   monnier@iro.umontreal.ca,  arthur.miller@live.com
> Date: Wed, 01 May 2024 16:54:04 -0400
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Without any discussion of what can be @var{type} and no examples, this
> > is too abstract.  I learned more about it from the other parts of the
> > changeset, where you actually use this.  So please say something about
> > what can be @var{type}, and add one or two examples.
> >
> > Also, should we say something in NEWS about this?
> 
> Entry added.
> 
> Please let me know if you like me to merge it or I can improve it
> further.

Thanks.  I still have a few minor comments below, but we can handle
these after this lands on master.

> +@var{type} is a type specifier in the form @code{(function (ARG-1-TYPE
> +... ARG-N-TYPE) RETURN-TYPE)}.  Argument types can be interleaved with

The @code{..} part should be wrapped in @w{..}, to prevent its
breaking between two lines.

> +symbols @code{&optional} and @code{&rest} to match the @pxref{Argument
> +List} of the function.

This is not a good use of @pxref.  You want @ref there.  Moreover,
such HTML-like style of cross-references doesn't work well in Texinfo,
because at least the info and the printed output formats add stuff,
like "See" to the reference.  So my recommendation is to use a wordier

  ...to match the function's arguments (@pxref{Argument List}).

> +@lisp
> +(defun positive-p (x)
> +  (declare (type (function (number) boolean)))
> +  (when (> x 0)
> +    t))
> +@end lisp

If you don't want to have the example broken between two pages, use
@group:

  @lisp
  @group
  (defun positive-p (x)
    (declare (type (function (number) boolean)))
    (when (> x 0)
      t))
  @end group
  @end lisp

> +@lisp
> +(defun cons-or-number (x &optional err-msg)
> +  (declare (type (function ((or cons number) &optional string)
> +			   (member is-cons is-number))))
> +  (if (consp x)
> +      'is-cons
> +    (if (numberp x)
> +	'is-number
> +      (error (or err-msg "Unexpected input")))))
> +@end lisp

Same here.

> +More types are described in @pxref{Lisp Data Types}.

The problematic cross-reference again.

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -1935,6 +1935,10 @@ unibyte string.
>  \f
>  * Lisp Changes in Emacs 30.1
>  
> +** Function type declaration

This should end in a period.  Also, since you have updated the manual,
it should be marked with "+++".

> +It is now possible, using the 'declare' macro, to declare expected types
> +of function arguments and return type.

Suggest to reword:

  It is now possible to declare the expected type of a function's
  arguments using the 'declare' macro.