Re: documentation of integers, fixnums and bignums

[Eli Zaretskii <eliz@gnu.org>]

> Cc: Emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Sat, 8 Sep 2018 13:05:48 -0700
> 
> Eli Zaretskii wrote:
> > 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.
> 
> When Lisp programmers care about object types, they should care only whether the 
> objects are integers.

Ideally, yes.  But in practice dealing with very large integers is
something people don't assume naturally, and for now bignums and
fixnums don't even behave identically in Emacs Lisp.

> What you see as "some distant future" I see as happening before the next 
> release, by the way. Perhaps that explains why you're more in favor of 
> documenting the current not-yet-finished situation, whereas I'm more in favor of 
> keeping the documentation simple and implementing it that way.

Well, that changeset started with an attempt to fix a woefully
misleading documentation left behind, which still claimed we produce
cons cells in some situations.  We must keep the master branch
reasonably well documented, because it is being used by a lot of
people.  We cannot leave it in WIP state for longer than a few hours.
When code changes, documentation should follow immediately.  Yes, that
means additional work, which might in the end prove more than
absolutely necessary, but I see no other way when development is done
incrementally on the master branch (as opposed to a feature branch).

Thanks.