Rollup merge of #59529 - DevQps:improve-rem-docs, r=cuviper

Added documentation on the remainder (Rem) operator for floating points.

# Description

As has been explained in #57738 the remainder operator on floating points is not clear.
This PR requests adds some information on how the `Rem` / remainder operator on floating points works.

Note also that this description is for both `Rem<f32> for f32` and `Rem<f64> for f64` implementations.

Ps. I wasn't really sure on how to formulate things. So please suggest changes if you have better idea's!

closes #57738

1 files changed, 15 insertions, 0 deletions

diff --git a/src/libcore/ops/arith.rs b/src/libcore/ops/arith.rs
index 28c9ff94dee..0688a606591 100644
--- a/src/libcore/ops/arith.rs
+++ b/src/libcore/ops/arith.rs
@@ -537,6 +537,21 @@ rem_impl_integer! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 
 macro_rules! rem_impl_float {
     ($($t:ty)*) => ($(
+
+        /// The remainder from the division of two floats.
+        ///
+        /// The remainder has the same sign as the dividend and is computed as:
+        /// `x - (x / y).trunc() * y`.
+        ///
+        /// # Examples
+        /// ```
+        /// let x: f32 = 50.50;
+        /// let y: f32 = 8.125;
+        /// let remainder = x - (x / y).trunc() * y;
+        ///
+        /// // The answer to both operations is 1.75
+        /// assert_eq!(x % y, remainder);
+        /// ```
         #[stable(feature = "rust1", since = "1.0.0")]
         impl Rem for $t {
             type Output = $t;