Re: Declaring Lisp function types

[Stefan Monnier]

>   @item (type @var{type})
>   Declare @var{type} to be the type of this function.  This is used for
>   documentation by @code{describe-function}.  Also it can be used by the
>   native compiler (@pxref{Native-Compilation}) for improving code
>   generation and for deriving more precisely the type of other functions
>   without type declaration.
>
> 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.

Thanks Eli for reminding me: as mentioned earlier, I think we should
clarify what are the possible consequences if a type does not faithfully
reflect the behavior of the function.  Examples of questions that one
should be able to answer based on the doc:

- Can an incorrect type affect Emacs' behavior (other than performance)?
- And if so, can it cause a crash?
- What if the type is/was right but an advice does
  not obey the original type of the advised function?

The doc doesn't need to answer those questions directly, but it should
describe the possible effects of type annotations in enough details that
we can answer those questions.


        Stefan