From a992f95e34cd9ccc514c4706812f0f14b130332c Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Sun, 3 May 2020 09:01:14 -0500 Subject: [PATCH 1/5] Add examples for std::f32 constants. And also point people to use the associated constants of f32 instead. --- src/libcore/num/f32.rs | 140 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index 32f4956328975..cdbdd70d6a1ed 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -18,15 +18,45 @@ use crate::num::FpCategory; /// The radix or base of the internal representation of `f32`. /// Use [`f32::RADIX`](../../std/primitive.f32.html#associatedconstant.RADIX) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let r = std::f32::RADIX; +/// +/// // correct way +/// let r = f32::RADIX; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const RADIX: u32 = f32::RADIX; /// Number of significant digits in base 2. /// Use [`f32::MANTISSA_DIGITS`](../../std/primitive.f32.html#associatedconstant.MANTISSA_DIGITS) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let d = std::f32::MANTISSA_DIGITS; +/// +/// // correct way +/// let d = f32::MANTISSA_DIGITS; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS; /// Approximate number of significant digits in base 10. /// Use [`f32::DIGITS`](../../std/primitive.f32.html#associatedconstant.DIGITS) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let d = std::f32::DIGITS; +/// +/// // correct way +/// let d = f32::DIGITS; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const DIGITS: u32 = f32::DIGITS; @@ -36,50 +66,160 @@ pub const DIGITS: u32 = f32::DIGITS; /// This is the difference between `1.0` and the next larger representable number. /// /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let e = std::f32::EPSILON; +/// +/// // correct way +/// let e = f32::EPSILON; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const EPSILON: f32 = f32::EPSILON; /// Smallest finite `f32` value. /// Use [`f32::MIN`](../../std/primitive.f32.html#associatedconstant.MIN) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f32::MIN; +/// +/// // correct way +/// let min = f32::MIN; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN: f32 = f32::MIN; /// Smallest positive normal `f32` value. /// Use [`f32::MIN_POSITIVE`](../../std/primitive.f32.html#associatedconstant.MIN_POSITIVE) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f32::MIN_POSITIVE; +/// +/// // correct way +/// let min = f32::MIN_POSITIVE; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_POSITIVE: f32 = f32::MIN_POSITIVE; /// Largest finite `f32` value. /// Use [`f32::MAX`](../../std/primitive.f32.html#associatedconstant.MAX) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let max = std::f32::MAX; +/// +/// // correct way +/// let max = f32::MAX; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MAX: f32 = f32::MAX; /// One greater than the minimum possible normal power of 2 exponent. /// Use [`f32::MIN_EXP`](../../std/primitive.f32.html#associatedconstant.MIN_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f32::MIN_EXP; +/// +/// // correct way +/// let min = f32::MIN_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_EXP: i32 = f32::MIN_EXP; /// Maximum possible power of 2 exponent. /// Use [`f32::MAX_EXP`](../../std/primitive.f32.html#associatedconstant.MAX_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let max = std::f32::MAX_EXP; +/// +/// // correct way +/// let max = f32::MAX_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MAX_EXP: i32 = f32::MAX_EXP; /// Minimum possible normal power of 10 exponent. /// Use [`f32::MIN_10_EXP`](../../std/primitive.f32.html#associatedconstant.MIN_10_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f32::MIN_10_EXP; +/// +/// // correct way +/// let min = f32::MIN_10_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_10_EXP: i32 = f32::MIN_10_EXP; /// Maximum possible power of 10 exponent. /// Use [`f32::MAX_10_EXP`](../../std/primitive.f32.html#associatedconstant.MAX_10_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let max = std::f32::MAX_10_EXP; +/// +/// // correct way +/// let max = f32::MAX_10_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MAX_10_EXP: i32 = f32::MAX_10_EXP; /// Not a Number (NaN). /// Use [`f32::NAN`](../../std/primitive.f32.html#associatedconstant.NAN) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let nan = std::f32::NAN; +/// +/// // correct way +/// let nan = f32::NAN; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const NAN: f32 = f32::NAN; /// Infinity (∞). /// Use [`f32::INFINITY`](../../std/primitive.f32.html#associatedconstant.INFINITY) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let inf = std::f32::INFINITY; +/// +/// // correct way +/// let inf = f32::INFINITY; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const INFINITY: f32 = f32::INFINITY; /// Negative infinity (−∞). /// Use [`f32::NEG_INFINITY`](../../std/primitive.f32.html#associatedconstant.NEG_INFINITY) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let ninf = std::f32::NEG_INFINITY; +/// +/// // correct way +/// let ninf = f32::NEG_INFINITY; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const NEG_INFINITY: f32 = f32::NEG_INFINITY; From 0768fa461c8491aa97185f3d512c462a8b38bbb2 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Sun, 3 May 2020 09:02:58 -0500 Subject: [PATCH 2/5] add some whitespace --- src/libcore/num/f32.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index cdbdd70d6a1ed..25b2c7c5ef4ea 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -45,6 +45,7 @@ pub const RADIX: u32 = f32::RADIX; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS; + /// Approximate number of significant digits in base 10. /// Use [`f32::DIGITS`](../../std/primitive.f32.html#associatedconstant.DIGITS) instead. /// @@ -93,6 +94,7 @@ pub const EPSILON: f32 = f32::EPSILON; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN: f32 = f32::MIN; + /// Smallest positive normal `f32` value. /// Use [`f32::MIN_POSITIVE`](../../std/primitive.f32.html#associatedconstant.MIN_POSITIVE) instead. /// @@ -107,6 +109,7 @@ pub const MIN: f32 = f32::MIN; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_POSITIVE: f32 = f32::MIN_POSITIVE; + /// Largest finite `f32` value. /// Use [`f32::MAX`](../../std/primitive.f32.html#associatedconstant.MAX) instead. /// @@ -136,6 +139,7 @@ pub const MAX: f32 = f32::MAX; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_EXP: i32 = f32::MIN_EXP; + /// Maximum possible power of 2 exponent. /// Use [`f32::MAX_EXP`](../../std/primitive.f32.html#associatedconstant.MAX_EXP) instead. /// @@ -165,6 +169,7 @@ pub const MAX_EXP: i32 = f32::MAX_EXP; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_10_EXP: i32 = f32::MIN_10_EXP; + /// Maximum possible power of 10 exponent. /// Use [`f32::MAX_10_EXP`](../../std/primitive.f32.html#associatedconstant.MAX_10_EXP) instead. /// @@ -194,6 +199,7 @@ pub const MAX_10_EXP: i32 = f32::MAX_10_EXP; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const NAN: f32 = f32::NAN; + /// Infinity (∞). /// Use [`f32::INFINITY`](../../std/primitive.f32.html#associatedconstant.INFINITY) instead. /// @@ -208,6 +214,7 @@ pub const NAN: f32 = f32::NAN; /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const INFINITY: f32 = f32::INFINITY; + /// Negative infinity (−∞). /// Use [`f32::NEG_INFINITY`](../../std/primitive.f32.html#associatedconstant.NEG_INFINITY) instead. /// From d38d429be74c8bad84d330ccdae95fcaf6f7c30a Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 4 May 2020 08:07:20 -0500 Subject: [PATCH 3/5] correct -> intended --- src/libcore/num/f32.rs | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index 25b2c7c5ef4ea..4483940c9a771 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -25,7 +25,7 @@ use crate::num::FpCategory; /// // deprecated way /// let r = std::f32::RADIX; /// -/// // correct way +/// // intended way /// let r = f32::RADIX; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -40,7 +40,7 @@ pub const RADIX: u32 = f32::RADIX; /// // deprecated way /// let d = std::f32::MANTISSA_DIGITS; /// -/// // correct way +/// // intended way /// let d = f32::MANTISSA_DIGITS; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -55,7 +55,7 @@ pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS; /// // deprecated way /// let d = std::f32::DIGITS; /// -/// // correct way +/// // intended way /// let d = f32::DIGITS; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -74,7 +74,7 @@ pub const DIGITS: u32 = f32::DIGITS; /// // deprecated way /// let e = std::f32::EPSILON; /// -/// // correct way +/// // intended way /// let e = f32::EPSILON; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -89,7 +89,7 @@ pub const EPSILON: f32 = f32::EPSILON; /// // deprecated way /// let min = std::f32::MIN; /// -/// // correct way +/// // intended way /// let min = f32::MIN; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -104,7 +104,7 @@ pub const MIN: f32 = f32::MIN; /// // deprecated way /// let min = std::f32::MIN_POSITIVE; /// -/// // correct way +/// // intended way /// let min = f32::MIN_POSITIVE; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -119,7 +119,7 @@ pub const MIN_POSITIVE: f32 = f32::MIN_POSITIVE; /// // deprecated way /// let max = std::f32::MAX; /// -/// // correct way +/// // intended way /// let max = f32::MAX; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -134,7 +134,7 @@ pub const MAX: f32 = f32::MAX; /// // deprecated way /// let min = std::f32::MIN_EXP; /// -/// // correct way +/// // intended way /// let min = f32::MIN_EXP; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -149,7 +149,7 @@ pub const MIN_EXP: i32 = f32::MIN_EXP; /// // deprecated way /// let max = std::f32::MAX_EXP; /// -/// // correct way +/// // intended way /// let max = f32::MAX_EXP; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -164,7 +164,7 @@ pub const MAX_EXP: i32 = f32::MAX_EXP; /// // deprecated way /// let min = std::f32::MIN_10_EXP; /// -/// // correct way +/// // intended way /// let min = f32::MIN_10_EXP; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -179,7 +179,7 @@ pub const MIN_10_EXP: i32 = f32::MIN_10_EXP; /// // deprecated way /// let max = std::f32::MAX_10_EXP; /// -/// // correct way +/// // intended way /// let max = f32::MAX_10_EXP; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -194,7 +194,7 @@ pub const MAX_10_EXP: i32 = f32::MAX_10_EXP; /// // deprecated way /// let nan = std::f32::NAN; /// -/// // correct way +/// // intended way /// let nan = f32::NAN; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -209,7 +209,7 @@ pub const NAN: f32 = f32::NAN; /// // deprecated way /// let inf = std::f32::INFINITY; /// -/// // correct way +/// // intended way /// let inf = f32::INFINITY; /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -224,7 +224,7 @@ pub const INFINITY: f32 = f32::INFINITY; /// // deprecated way /// let ninf = std::f32::NEG_INFINITY; /// -/// // correct way +/// // intended way /// let ninf = f32::NEG_INFINITY; /// ``` #[stable(feature = "rust1", since = "1.0.0")] From 8bef0a3683c0a5dad40ee5889364ba206fc3af1f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 4 May 2020 08:14:38 -0500 Subject: [PATCH 4/5] f64 examples --- src/libcore/num/f64.rs | 147 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs index b38fd804ee80f..587f069312f72 100644 --- a/src/libcore/num/f64.rs +++ b/src/libcore/num/f64.rs @@ -18,15 +18,46 @@ use crate::num::FpCategory; /// The radix or base of the internal representation of `f64`. /// Use [`f64::RADIX`](../../std/primitive.f64.html#associatedconstant.RADIX) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let r = std::f64::RADIX; +/// +/// // intended way +/// let r = f64::RADIX; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const RADIX: u32 = f64::RADIX; /// Number of significant digits in base 2. /// Use [`f64::MANTISSA_DIGITS`](../../std/primitive.f64.html#associatedconstant.MANTISSA_DIGITS) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let d = std::f64::MANTISSA_DIGITS; +/// +/// // intended way +/// let d = f64::MANTISSA_DIGITS; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MANTISSA_DIGITS: u32 = f64::MANTISSA_DIGITS; + /// Approximate number of significant digits in base 10. /// Use [`f64::DIGITS`](../../std/primitive.f64.html#associatedconstant.DIGITS) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let d = std::f64::DIGITS; +/// +/// // intended way +/// let d = f64::DIGITS; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const DIGITS: u32 = f64::DIGITS; @@ -36,50 +67,166 @@ pub const DIGITS: u32 = f64::DIGITS; /// This is the difference between `1.0` and the next larger representable number. /// /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let e = std::f64::EPSILON; +/// +/// // intended way +/// let e = f64::EPSILON; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const EPSILON: f64 = f64::EPSILON; /// Smallest finite `f64` value. /// Use [`f64::MIN`](../../std/primitive.f64.html#associatedconstant.MIN) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f64::MIN; +/// +/// // intended way +/// let min = f64::MIN; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN: f64 = f64::MIN; + /// Smallest positive normal `f64` value. /// Use [`f64::MIN_POSITIVE`](../../std/primitive.f64.html#associatedconstant.MIN_POSITIVE) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f64::MIN_POSITIVE; +/// +/// // intended way +/// let min = f64::MIN_POSITIVE; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_POSITIVE: f64 = f64::MIN_POSITIVE; + /// Largest finite `f64` value. /// Use [`f64::MAX`](../../std/primitive.f64.html#associatedconstant.MAX) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let max = std::f64::MAX; +/// +/// // intended way +/// let max = f64::MAX; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MAX: f64 = f64::MAX; /// One greater than the minimum possible normal power of 2 exponent. /// Use [`f64::MIN_EXP`](../../std/primitive.f64.html#associatedconstant.MIN_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f64::MIN_EXP; +/// +/// // intended way +/// let min = f64::MIN_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_EXP: i32 = f64::MIN_EXP; + /// Maximum possible power of 2 exponent. /// Use [`f64::MAX_EXP`](../../std/primitive.f64.html#associatedconstant.MAX_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let max = std::f64::MAX_EXP; +/// +/// // intended way +/// let max = f64::MAX_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MAX_EXP: i32 = f64::MAX_EXP; /// Minimum possible normal power of 10 exponent. /// Use [`f64::MIN_10_EXP`](../../std/primitive.f64.html#associatedconstant.MIN_10_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let min = std::f64::MIN_10_EXP; +/// +/// // intended way +/// let min = f64::MIN_10_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_10_EXP: i32 = f64::MIN_10_EXP; + /// Maximum possible power of 10 exponent. /// Use [`f64::MAX_10_EXP`](../../std/primitive.f64.html#associatedconstant.MAX_10_EXP) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let max = std::f64::MAX_10_EXP; +/// +/// // intended way +/// let max = f64::MAX_10_EXP; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const MAX_10_EXP: i32 = f64::MAX_10_EXP; /// Not a Number (NaN). /// Use [`f64::NAN`](../../std/primitive.f64.html#associatedconstant.NAN) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let nan = std::f64::NAN; +/// +/// // intended way +/// let nan = f64::NAN; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const NAN: f64 = f64::NAN; + /// Infinity (∞). /// Use [`f64::INFINITY`](../../std/primitive.f64.html#associatedconstant.INFINITY) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let inf = std::f64::INFINITY; +/// +/// // intended way +/// let inf = f64::INFINITY; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const INFINITY: f64 = f64::INFINITY; + /// Negative infinity (−∞). /// Use [`f64::NEG_INFINITY`](../../std/primitive.f64.html#associatedconstant.NEG_INFINITY) instead. +/// +/// # Examples +/// +/// ```rust +/// // deprecated way +/// let ninf = std::f64::NEG_INFINITY; +/// +/// // intended way +/// let ninf = f64::NEG_INFINITY; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const NEG_INFINITY: f64 = f64::NEG_INFINITY; From 55e37f9f02af4eec5c52413e3219bef838beadab Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 4 May 2020 08:26:39 -0500 Subject: [PATCH 5/5] Add examples to int macros --- src/libcore/num/int_macros.rs | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/src/libcore/num/int_macros.rs b/src/libcore/num/int_macros.rs index 5035445ba939f..ffd30b03f2109 100644 --- a/src/libcore/num/int_macros.rs +++ b/src/libcore/num/int_macros.rs @@ -12,14 +12,36 @@ macro_rules! int_module { ($T:ident, #[$attr:meta]) => ( doc_comment! { concat!("The smallest value that can be represented by this integer type. -Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead."), +Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead. + +# Examples + +```rust +// deprecated way +let min = std::", stringify!($T), "::MIN; + +// intended way +let min = ", stringify!($T), "::MIN; +``` +"), #[$attr] pub const MIN: $T = $T::MIN; } doc_comment! { concat!("The largest value that can be represented by this integer type. -Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead."), +Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead. + +# Examples + +```rust +// deprecated way +let max = std::", stringify!($T), "::MAX; + +// intended way +let max = ", stringify!($T), "::MAX; +``` +"), #[$attr] pub const MAX: $T = $T::MAX; }