From a6bbd0c1caf9cac76fc91700245a1bb51caddf3e Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 7 Jul 2016 23:02:10 +0200 Subject: [PATCH] Improve primitive integers documentation --- src/libcore/num/mod.rs | 32 ++++++++++++++++++++++++++++++++ src/libstd/primitive_docs.rs | 30 ++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index b41ef7984bb..7dd9ecedb56 100644 --- a/src/libcore/num/mod.rs +++ b/src/libcore/num/mod.rs @@ -187,6 +187,12 @@ macro_rules! int_impl { $sub_with_overflow:path, $mul_with_overflow:path) => { /// Returns the smallest value that can be represented by this integer type. + /// + /// # Examples + /// + /// ``` + /// assert_eq!(i8::min_value(), -128); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub const fn min_value() -> Self { @@ -194,6 +200,12 @@ macro_rules! int_impl { } /// Returns the largest value that can be represented by this integer type. + /// + /// # Examples + /// + /// ``` + /// assert_eq!(i8::max_value(), 127); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub const fn max_value() -> Self { @@ -287,6 +299,8 @@ macro_rules! int_impl { /// Shifts the bits to the left by a specified amount, `n`, /// wrapping the truncated bits to the end of the resulting integer. /// + /// Please note this isn't the same operation as `<<`! + /// /// # Examples /// /// Basic usage: @@ -307,6 +321,8 @@ macro_rules! int_impl { /// wrapping the truncated bits to the beginning of the resulting /// integer. /// + /// Please note this isn't the same operation as `>>`! + /// /// # Examples /// /// Basic usage: @@ -1249,11 +1265,23 @@ macro_rules! uint_impl { $sub_with_overflow:path, $mul_with_overflow:path) => { /// Returns the smallest value that can be represented by this integer type. + /// + /// # Examples + /// + /// ``` + /// assert_eq!(u8::min_value(), 0); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub const fn min_value() -> Self { 0 } /// Returns the largest value that can be represented by this integer type. + /// + /// # Examples + /// + /// ``` + /// assert_eq!(u8::max_value(), 255); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] #[inline] pub const fn max_value() -> Self { !0 } @@ -1360,6 +1388,8 @@ macro_rules! uint_impl { /// Shifts the bits to the left by a specified amount, `n`, /// wrapping the truncated bits to the end of the resulting integer. /// + /// Please note this isn't the same operation as `<<`! + /// /// # Examples /// /// Basic usage: @@ -1382,6 +1412,8 @@ macro_rules! uint_impl { /// wrapping the truncated bits to the beginning of the resulting /// integer. /// + /// Please note this isn't the same operation as `>>`! + /// /// # Examples /// /// Basic usage: diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index be9cd6a6888..de891ea8918 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -506,6 +506,9 @@ mod prim_f64 { } /// /// *[See also the `std::i8` module](i8/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `i64` in there. +/// mod prim_i8 { } #[doc(primitive = "i16")] @@ -514,6 +517,9 @@ mod prim_i8 { } /// /// *[See also the `std::i16` module](i16/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `i32` in there. +/// mod prim_i16 { } #[doc(primitive = "i32")] @@ -522,6 +528,9 @@ mod prim_i16 { } /// /// *[See also the `std::i32` module](i32/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `i16` in there. +/// mod prim_i32 { } #[doc(primitive = "i64")] @@ -530,6 +539,9 @@ mod prim_i32 { } /// /// *[See also the `std::i64` module](i64/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `i8` in there. +/// mod prim_i64 { } #[doc(primitive = "u8")] @@ -538,6 +550,9 @@ mod prim_i64 { } /// /// *[See also the `std::u8` module](u8/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `u64` in there. +/// mod prim_u8 { } #[doc(primitive = "u16")] @@ -546,6 +561,9 @@ mod prim_u8 { } /// /// *[See also the `std::u16` module](u16/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `u32` in there. +/// mod prim_u16 { } #[doc(primitive = "u32")] @@ -554,6 +572,9 @@ mod prim_u16 { } /// /// *[See also the `std::u32` module](u32/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `u16` in there. +/// mod prim_u32 { } #[doc(primitive = "u64")] @@ -562,6 +583,9 @@ mod prim_u32 { } /// /// *[See also the `std::u64` module](u64/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `u8` in there. +/// mod prim_u64 { } #[doc(primitive = "isize")] @@ -570,6 +594,9 @@ mod prim_u64 { } /// /// *[See also the `std::isize` module](isize/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `usize` in there. +/// mod prim_isize { } #[doc(primitive = "usize")] @@ -578,4 +605,7 @@ mod prim_isize { } /// /// *[See also the `std::usize` module](usize/index.html).* /// +/// However, please note that examples are shared between primitive integer +/// types. So it's normal if you see usage of types like `isize` in there. +/// mod prim_usize { }