documentation of integers, fixnums and bignums

[Paul Eggert]

>  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.

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.