From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string Date: Tue, 19 Jul 2022 17:26:44 +0300 Message-ID: <83v8rtmb4r.fsf@gnu.org> References: <831quhnrf8.fsf@gnu.org> <063D21A9-801C-411B-B59C-AA7A057DFF79@acm.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="22778"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Mattias =?utf-8?Q?Engdeg=C3=A5rd?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Jul 19 16:42:44 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oDoQt-0005nY-Qz for ged-emacs-devel@m.gmane-mx.org; Tue, 19 Jul 2022 16:42:44 +0200 Original-Received: from localhost ([::1]:48332 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oDoQs-0005Mu-PM for ged-emacs-devel@m.gmane-mx.org; Tue, 19 Jul 2022 10:42:42 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58976) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oDoBf-0006fb-BL for emacs-devel@gnu.org; Tue, 19 Jul 2022 10:27:00 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:36216) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oDoBe-0000qQ-Sk; Tue, 19 Jul 2022 10:26:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=7YBZhnu+471JkCzbi5jJeVyeIppnnFYgPUwZHd9BrL8=; b=hSu5Io1e2+jArSC6rGKD 5EIPzuAuMzgtZ6avFAsNk+Eq4fRCpQi1EYGbuwy+Qcw2qntIM4+ZGgQexuA7Gmb07OOPUi/10UIIf 8vGaSE1hYGjQlWFeKctuT9P3KdVX1k7O7JY1gJ857z+3yjJVE6GxuDKM6XrXzMCkzIPiZJODM/msH ngYZar+YQkach4vGDbnCSYY8ueNqa5rJV5+SDdrOlae2lwm380J+JGNk2NzyuCrTONoNfZ7w7Xrfz njC6xdFqI1Q4wTgVE+IYVq4CA8iYZQe2Y2DzuqlZTD398MSTCf3e5IxYSFcQZRnIusNF3og64cmEG KAB4yrqSIdmoPA==; Original-Received: from [87.69.77.57] (port=3101 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oDoBb-0004hA-Dl; Tue, 19 Jul 2022 10:26:58 -0400 In-Reply-To: <063D21A9-801C-411B-B59C-AA7A057DFF79@acm.org> (message from Mattias =?utf-8?Q?Engdeg=C3=A5rd?= on Tue, 19 Jul 2022 16:19:52 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:292270 Archived-At: > From: Mattias Engdegård > Date: Tue, 19 Jul 2022 16:19:52 +0200 > Cc: emacs-devel@gnu.org > > 19 juli 2022 kl. 15.49 skrev Eli Zaretskii : > > > I'm afraid I find the modified doc string less self-explanatory wrt > > what happens when VALUE is negative. It might be more accurate, but > > makes it harder to understand what happens in that case. > > The old text was definitely not self-explanatory; it made me more confused than enlightened. > But let's try again. What about: > > Return VALUE with its bits shifted left by COUNT. > If COUNT is negative, shifting is actually to the right. > Values are shifted as an infinitely wide two's complement representation; each shift step multiplies (left-shifting) or divides (right-shifting) the value by two, rounding down. > VALUE and COUNT must be integers. IMO, that's too technical, and thus too demanding on the reader: . it requires the reader to know about two's complement representation . it requires the reader to imagine "infinitely-wide" binary values . it requires the reader to understand that shifting, multiplication, and division are equivalent . it requires the reader to understand the notion of "rounding down" How about explaining in simple words what this does to positive and negative values shifted left and right? One possible way to explain that is what the ELisp manual does. But it isn't the only one.