unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* documentation of integers, fixnums and bignums
@ 2018-09-08 16:09 Paul Eggert
  2018-09-08 16:27 ` Eli Zaretskii
  0 siblings, 1 reply; 18+ messages in thread
From: Paul Eggert @ 2018-09-08 16:09 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Emacs Development

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



^ permalink raw reply	[flat|nested] 18+ messages in thread

end of thread, other threads:[~2018-09-10 13:53 UTC | newest]

Thread overview: 18+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <<0f632217-27ad-4f54-8ce0-480301fa2a86@cs.ucla.edu>
     [not found] ` <<83pnxorm37.fsf@gnu.org>
2018-09-09  1:43   ` documentation of integers, fixnums and bignums Drew Adams
2018-09-08 16:09 Paul Eggert
2018-09-08 16:27 ` Eli Zaretskii
2018-09-08 18:15   ` Stefan Monnier
2018-09-08 20:15     ` Paul Eggert
2018-09-08 22:03       ` Stefan Monnier
2018-09-08 23:37         ` Paul Eggert
2018-09-09  2:33           ` Stefan Monnier
2018-09-09  5:40           ` Eli Zaretskii
2018-09-10  0:09             ` Stefan Monnier
2018-09-10  6:43               ` Eli Zaretskii
2018-09-10 12:11                 ` Stefan Monnier
2018-09-10 13:53                   ` Eli Zaretskii
2018-09-09  5:42         ` Eli Zaretskii
2018-09-10  0:12           ` Stefan Monnier
2018-09-08 20:05   ` Paul Eggert
2018-09-08 21:07     ` Eli Zaretskii
2018-09-08 21:58     ` Stefan Monnier

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).