|
From: | Paul Eggert |
Subject: | documentation of integers, fixnums and bignums |
Date: | Sat, 8 Sep 2018 09:09:03 -0700 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 |
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.
[Prev in Thread] | Current Thread | [Next in Thread] |