Re: master ac1d15e95c 1/2: ; * src/data.c (Fash): More precise doc string

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Tue, 19 Jul 2022 16:19:52 +0200
> Cc: emacs-devel@gnu.org
> 
> 19 juli 2022 kl. 15.49 skrev Eli Zaretskii <eliz@gnu.org>:
> 
> > 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.