Sync docs for js_math.ml #5441
Sync docs for js_math.ml #5441
Conversation
| (** | ||
| Raises the given base to the given exponent. (Arguments and result are | ||
| integers.) See | ||
| [`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow) | ||
| on MDN. | ||
|
|
||
| ```res example | ||
| Js.Math.pow_int(~base=3, ~exp=4) == 81 | ||
| ``` | ||
| *) | ||
| external pow_int : base:int -> exp:int -> int = "pow" [@@bs.val] [@@bs.scope "Math"] | ||
| [@@deprecated "use `power_float` instead, the return type may be not int"] |
There was a problem hiding this comment.
Inconsistent gotcha here. The pow_int function is deprecated but docs in mdx do not mention it. For now, I copied the docs as is, without the deprecation notice.
However, looking at other similar cases (unsafe_ceil_int / ceil_int, unsafe_round, unsafe_trunc) to be consistent:
pow_intshould be renamed tounsafe_pow_int- The documentation should include the standard explanation of range issues¹
- A new function
pow_intwhich is an alias to theunsafe_pow_intshould be introduced and deprecated immediatelly pow_intdocs should say “please, useunsafe_pow_int
¹
This function may return values not representable by
int, whose range is -2147483648 to 2147483647. This is because, in JavaScript, there are only 64-bit floating point numbers, which can represent integers in the range ±(253-1) exactly.
Should I do it now or it is a task for the latter, when the whole docs PR settles down?
There was a problem hiding this comment.
maybe let's have a separate issue and tackle this after the transition? There shouldn't be any semantic changes.
There was a problem hiding this comment.
Sure. So for now, I guess the PR is ready for merge.
No description provided.