From e8eb80b9de9bacf2809e9b068c1b4a97cbea8736 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Sun, 10 May 2026 12:19:26 +0100
Subject: [PATCH] Improve doc comments for f32::ceil() and f32::floor()

Previously ::floor() included an example showing behaviour for
negative values, but ::ceil() did not. Ensure both have examples of
the negative case, for both f32 and f64.

Whilst we're here, tweak the wording slightly so it reads better.
---
 library/std/src/num/f32.rs | 6 ++++--
 library/std/src/num/f64.rs | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/library/std/src/num/f32.rs b/library/std/src/num/f32.rs
index 4f38d3be52f7..3c1778cae6e2 100644
--- a/library/std/src/num/f32.rs
+++ b/library/std/src/num/f32.rs
@@ -26,7 +26,7 @@
 
 #[cfg(not(test))]
 impl f32 {
-    /// Returns the largest integer less than or equal to `self`.
+    /// Returns the largest integer that is less than or equal to `self`.
     ///
     /// This function always returns the precise result.
     ///
@@ -50,7 +50,7 @@ pub const fn floor(self) -> f32 {
         core::f32::math::floor(self)
     }
 
-    /// Returns the smallest integer greater than or equal to `self`.
+    /// Returns the smallest integer that is greater than or equal to `self`.
     ///
     /// This function always returns the precise result.
     ///
@@ -59,9 +59,11 @@ pub const fn floor(self) -> f32 {
     /// ```
     /// let f = 3.01_f32;
     /// let g = 4.0_f32;
+    /// let h = -3.01_f32;
     ///
     /// assert_eq!(f.ceil(), 4.0);
     /// assert_eq!(g.ceil(), 4.0);
+    /// assert_eq!(h.ceil(), -3.0);
     /// ```
     #[doc(alias = "ceiling")]
     #[rustc_allow_incoherent_impl]
diff --git a/library/std/src/num/f64.rs b/library/std/src/num/f64.rs
index 8a771185f6fe..af262474f1b0 100644
--- a/library/std/src/num/f64.rs
+++ b/library/std/src/num/f64.rs
@@ -26,7 +26,7 @@
 
 #[cfg(not(test))]
 impl f64 {
-    /// Returns the largest integer less than or equal to `self`.
+    /// Returns the largest integer that is less than or equal to `self`.
     ///
     /// This function always returns the precise result.
     ///
@@ -50,7 +50,7 @@ pub const fn floor(self) -> f64 {
         core::f64::math::floor(self)
     }
 
-    /// Returns the smallest integer greater than or equal to `self`.
+    /// Returns the smallest integer that is greater than or equal to `self`.
     ///
     /// This function always returns the precise result.
     ///
@@ -59,9 +59,11 @@ pub const fn floor(self) -> f64 {
     /// ```
     /// let f = 3.01_f64;
     /// let g = 4.0_f64;
+    /// let h = -3.01_f64;
     ///
     /// assert_eq!(f.ceil(), 4.0);
     /// assert_eq!(g.ceil(), 4.0);
+    /// assert_eq!(h.ceil(), -3.0);
     /// ```
     #[doc(alias = "ceiling")]
     #[rustc_allow_incoherent_impl]