Re: documentation of integers, fixnums and bignums

[Eli Zaretskii <eliz@gnu.org>]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: Emacs Development <Emacs-devel@gnu.org>
> Date: Sat, 8 Sep 2018 09:09:03 -0700
> 
> >  DEFUN ("encode-char", Fencode_char, Sencode_char, 2, 2, 0,
> >         doc: /* Encode the character CH into a code-point of CHARSET.
> > -Return nil if CHARSET doesn't include CH.  */)
> > +Return the encoded code-point, a fixnum if its value is small enough,
> > +otherwise a bignum.
> > +Return nil if CHARSET doesn't support CH.  */)
> 
> As the intent is that Emacs should treat integers transparently, so that 
> ordinary code needn't worry about the difference between bignums and fixnums, it 
> would be better if documentation like this simply says something like "Return 
> the encoded code-point, an integer", as this is more concise.

Sorry, I disagree.  I think it's important for the Lisp programmers to
know what kind of objects they could get as return values.  Maybe in
some distant future we will no longer care about the difference
between fixnums and bignums, but as of now, we still do.

I've left the ELisp manual documentation which says "number" without
these details, but I think at least the doc strings should spell out
these details, for now.

> It's true that the current integer implementation is a bit different, in that eq 
> and = now treat integers differently; but this is a global property that is best 
> documented in the integer section of the Emacs manual. We shouldn't need to add 
> a comment in each function returning an integer in effect saying "watch out! eq 
> and = might act differently on these integers!" as the cost to users of this 
> documentation complication will exceed its benefit in the long run.

I think we should call out the functions that can return bignums
because of this and other peculiarities of bignums.  Otherwise, people
will have hard time writing robust programs that use these APIs.
E.g., it would take an expert in obscure character sets to know that
encode-char could potentially return a value that cannot be
represented as a fixnum.