Improve floating point documentation about platform guarantees #95468
Labels
A-floating-point
Area: Floating point numbers and arithmetic
Comments
|
I'm working on this currently. |
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this issue
May 9, 2022
…shtriplett Improve floating point documentation This is my attempt to improve/solve rust-lang#95468 and rust-lang#73328 . Added/refined explanations: - Refine the "NaN as a special value" top level explanation of f32 - Refine `const NAN` docstring: add an explanation about there being multitude of NaN bitpatterns and disclaimer about the portability/stability guarantees. - Refine `fn is_sign_positive` and `fn is_sign_negative` docstrings: add disclaimer about the sign bit of NaNs. - Refine `fn min` and `fn max` docstrings: explain the semantics and their relationship to the standard and libm better. - Refine `fn trunc` docstrings: explain the semantics slightly more. - Refine `fn powi` docstrings: add disclaimer that the rounding behaviour might be different from `powf`. - Refine `fn copysign` docstrings: add disclaimer about payloads of NaNs. - Refine `minimum` and `maximum`: add disclaimer that "propagating NaN" doesn't mean that propagating the NaN bit patterns is guaranteed. - Refine `max` and `min` docstrings: add "ignoring NaN" to bring the one-row explanation to parity with `minimum` and `maximum`. Cosmetic changes: - Reword `NaN` and `NAN` as plain "NaN", unless they refer to the specific `const NAN`. - Reword "a number" to `self` in function docstrings to clarify. - Remove "Returns NAN if the number is NAN" from `abs`, as this is told to be the default behavior in the top explanation.
workingjubilee
pushed a commit
to tcdi/postgrestd
that referenced
this issue
Sep 15, 2022
Improve floating point documentation This is my attempt to improve/solve rust-lang/rust#95468 and rust-lang/rust#73328 . Added/refined explanations: - Refine the "NaN as a special value" top level explanation of f32 - Refine `const NAN` docstring: add an explanation about there being multitude of NaN bitpatterns and disclaimer about the portability/stability guarantees. - Refine `fn is_sign_positive` and `fn is_sign_negative` docstrings: add disclaimer about the sign bit of NaNs. - Refine `fn min` and `fn max` docstrings: explain the semantics and their relationship to the standard and libm better. - Refine `fn trunc` docstrings: explain the semantics slightly more. - Refine `fn powi` docstrings: add disclaimer that the rounding behaviour might be different from `powf`. - Refine `fn copysign` docstrings: add disclaimer about payloads of NaNs. - Refine `minimum` and `maximum`: add disclaimer that "propagating NaN" doesn't mean that propagating the NaN bit patterns is guaranteed. - Refine `max` and `min` docstrings: add "ignoring NaN" to bring the one-row explanation to parity with `minimum` and `maximum`. Cosmetic changes: - Reword `NaN` and `NAN` as plain "NaN", unless they refer to the specific `const NAN`. - Reword "a number" to `self` in function docstrings to clarify. - Remove "Returns NAN if the number is NAN" from `abs`, as this is told to be the default behavior in the top explanation.
workingjubilee
added
the
A-floating-point
RalfJung
changed the title
|
What is this issue still tracking? Some improvements landed in #95483. The issue description as it is is too vague to be actionable. |
|
Agreed! Closing this. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
As summarized in #72599 (comment), floating points have both some 1) platform-specific behaviour 2) surprising behaviour because of LLVM guarantees (or lack of thereof). Issue #73328 seems to be about improving the documentation about the LLVM-induced stuff, but mention about platform-specific behaviour also seems to be missing in some documentation items, so add some explanations/disclaimers about that.
The text was updated successfully, but these errors were encountered: