Which argument is which, for bit-shift-left and bit-shift-right?

Question

The docstring for (bit-shift-left x n) says only "Bitwise shift left". It does not define either x or n.

Below the docstring is a link to the source code, but it does not immediately clear up the question, as it delegates to a method of clojure.lang.Number.

Suggestion: enhance the docstring along the lines of "Bitwise shift x left by n bits".

P.S. Does left mean more-significant everywhere nowadays? As Clojure gets implemented in JS and even stranger environments, could the docstring clarify whether Clojure's left and right have a specified mathematical significance (as the Java Language Specification does) or have host-dependent significance?

P.P.S. Likewise, bit-shift-right.

P.P.P.S. Likewise in the ClojureScript docstrings.

Answer 1

Filed jira: https://clojure.atlassian.net/browse/CLJ-2608

Answer 2

You can easily get answers in your REPL

clj Clojure 1.10.1 (bit-shift-left 1 1) 2 (bit-shift-left 1 2) 4 (bit-shift-left 1 3) 8 (bit-shift-left 1 4) 16 (bit-shift-left 2 1) 4 (bit-shift-left 2 3) 16

these answers will be true. Even if you are running a custom 16-bit JVM on a SNES or if you are running on a odd javascript engine ;)

Comments

The question was about improving docstrings.