From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: documentation of integers, fixnums and bignums Date: Sat, 8 Sep 2018 09:09:03 -0700 Organization: UCLA Computer Science Department Message-ID: <0f632217-27ad-4f54-8ce0-480301fa2a86@cs.ucla.edu> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1536422835 9136 195.159.176.226 (8 Sep 2018 16:07:15 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 8 Sep 2018 16:07:15 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 Cc: Emacs Development To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Sep 08 18:07:11 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fyflN-0002GS-96 for ged-emacs-devel@m.gmane.org; Sat, 08 Sep 2018 18:07:09 +0200 Original-Received: from localhost ([::1]:43546 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fyfnT-000420-CT for ged-emacs-devel@m.gmane.org; Sat, 08 Sep 2018 12:09:19 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40352) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fyfnK-00040S-Fz for Emacs-devel@gnu.org; Sat, 08 Sep 2018 12:09:11 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fyfnH-00048q-4z for Emacs-devel@gnu.org; Sat, 08 Sep 2018 12:09:10 -0400 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:39976) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fyfnG-000452-TM; Sat, 08 Sep 2018 12:09:07 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 1E73D160DFE; Sat, 8 Sep 2018 09:09:04 -0700 (PDT) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id BDbTen5TZBaR; Sat, 8 Sep 2018 09:09:03 -0700 (PDT) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 66DEA160EC0; Sat, 8 Sep 2018 09:09:03 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id bwTQpWqPGmwq; Sat, 8 Sep 2018 09:09:03 -0700 (PDT) Original-Received: from [192.168.1.9] (cpe-23-242-74-103.socal.res.rr.com [23.242.74.103]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 44C29160E71; Sat, 8 Sep 2018 09:09:03 -0700 (PDT) Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 131.179.128.68 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:229497 Archived-At: > 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.