From 993f13a2cf125610dc6a34bf68aa6afd87a723d6 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Wed, 27 Apr 2016 23:29:49 -0400 Subject: [PATCH 01/24] update documentation of tuple/unit structs I made the "tuple structs are useless" editorializing a bit weaker and moved it to the end. Feel free to overrule me on that. I also added an example of how to unpack a tuple struct with dot notation, because it came up on IRC. `braced_empty_structs` is stable now, so I updated the example for unit-like structs to use that syntax. Should we show both ways? cc @ubsan r? @steveklabnik or @GuillameGomez --- src/doc/book/structs.md | 63 +++++++++++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 22 deletions(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index b2fddf336273f..404eac25308c0 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -163,11 +163,48 @@ struct Point(i32, i32, i32); let black = Color(0, 0, 0); let origin = Point(0, 0, 0); ``` + Here, `black` and `origin` are not equal, even though they contain the same values. -It is almost always better to use a `struct` than a tuple struct. We -would write `Color` and `Point` like this instead: +The members of a tuple struct may be accessed by dot notation or destructuring +`let`, just like regular tuples: + +```rust +# struct Color(i32, i32, i32); +# struct Point(i32, i32, i32); +# let black = Color(0, 0, 0); +# let origin = Point(0, 0, 0); +let black_r = black.0; +let (_, origin_y, origin_z) = origin; +``` + +One case when a tuple struct is very useful is when it has only one element. +We call this the ‘newtype’ pattern, because it allows you to create a new type +that is distinct from its contained value and also expresses its own semantic +meaning: + +```rust +struct Inches(i32); + +let length = Inches(10); + +let Inches(integer_length) = length; +println!("length is {} inches", integer_length); +``` + +As above, you can extract the inner integer type through a destructuring `let`. +In this case, the `let Inches(integer_length)` assigns `10` to `integer_length`. +We could have used dot notation to do the same thing: + +```rust +# struct Inches(i32); +# let length = Inches(10); +let integer_length = length.0; +``` + +It's always possible to use a `struct` than a tuple struct, and can be clearer. +We would write `Color` and `Point` like this instead: ```rust struct Color { @@ -187,32 +224,14 @@ Good names are important, and while values in a tuple struct can be referenced with dot notation as well, a `struct` gives us actual names, rather than positions. -There _is_ one case when a tuple struct is very useful, though, and that is when -it has only one element. We call this the ‘newtype’ pattern, because -it allows you to create a new type that is distinct from its contained value -and also expresses its own semantic meaning: - -```rust -struct Inches(i32); - -let length = Inches(10); - -let Inches(integer_length) = length; -println!("length is {} inches", integer_length); -``` - -As you can see here, you can extract the inner integer type through a -destructuring `let`, as with regular tuples. In this case, the -`let Inches(integer_length)` assigns `10` to `integer_length`. - # Unit-like structs You can define a `struct` with no members at all: ```rust -struct Electron; +struct Electron {} -let x = Electron; +let x = Electron {}; ``` Such a `struct` is called ‘unit-like’ because it resembles the empty From a14df5cc64053beabc03ceb5b6b1352cb48d166c Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 01:20:54 -0400 Subject: [PATCH 02/24] fix Point destructuring example --- src/doc/book/structs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 404eac25308c0..44a6d282c0002 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -176,7 +176,7 @@ The members of a tuple struct may be accessed by dot notation or destructuring # let black = Color(0, 0, 0); # let origin = Point(0, 0, 0); let black_r = black.0; -let (_, origin_y, origin_z) = origin; +let Point(_, origin_y, origin_z) = origin; ``` One case when a tuple struct is very useful is when it has only one element. From beec630863e9453c79b2f970323639ab1fe8e853 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 10:32:08 -0400 Subject: [PATCH 03/24] "equal" -> "same type" --- src/doc/book/structs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 44a6d282c0002..34f50e905dd79 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -164,8 +164,8 @@ let black = Color(0, 0, 0); let origin = Point(0, 0, 0); ``` -Here, `black` and `origin` are not equal, even though they contain the same -values. +Here, `black` and `origin` are not the same type, even though they contain the +same values. The members of a tuple struct may be accessed by dot notation or destructuring `let`, just like regular tuples: From e1e4fbd2a235e9ce31bd614dff667a81b8f8c360 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 10:47:19 -0400 Subject: [PATCH 04/24] s/than/instead of/ --- src/doc/book/structs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 34f50e905dd79..eace99670b1ef 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -203,8 +203,8 @@ We could have used dot notation to do the same thing: let integer_length = length.0; ``` -It's always possible to use a `struct` than a tuple struct, and can be clearer. -We would write `Color` and `Point` like this instead: +It's always possible to use a `struct` instead of a tuple struct, and can be +clearer. We could write `Color` and `Point` like this instead: ```rust struct Color { From 56f24d7c193da3b972994e24b86e1fd63e1e8c9e Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 11:47:03 -0400 Subject: [PATCH 05/24] add link to match section --- src/doc/book/structs.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index eace99670b1ef..1fb74e33a622f 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -179,6 +179,9 @@ let black_r = black.0; let Point(_, origin_y, origin_z) = origin; ``` +Patterns like `Point(_, origin_y, origin_z)` are also used in +[match expressions][match]. + One case when a tuple struct is very useful is when it has only one element. We call this the ‘newtype’ pattern, because it allows you to create a new type that is distinct from its contained value and also expresses its own semantic @@ -224,6 +227,8 @@ Good names are important, and while values in a tuple struct can be referenced with dot notation as well, a `struct` gives us actual names, rather than positions. +[match]: match.html + # Unit-like structs You can define a `struct` with no members at all: From db26b3f5bcc49768a04867d5a21906f2bca4aa4a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 28 Apr 2016 23:51:42 +0200 Subject: [PATCH 06/24] doc: some `peek` improvements --- src/libcore/iter/mod.rs | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs index 17f7c0a773e68..6ad905b6b261d 100644 --- a/src/libcore/iter/mod.rs +++ b/src/libcore/iter/mod.rs @@ -1048,17 +1048,15 @@ impl ExactSizeIterator for Peekable {} impl Peekable { /// Returns a reference to the next() value without advancing the iterator. /// - /// The `peek()` method will return the value that a call to [`next()`] would - /// return, but does not advance the iterator. Like [`next()`], if there is - /// a value, it's wrapped in a `Some(T)`, but if the iterator is over, it - /// will return `None`. + /// Like [`next()`], if there is a value, it is wrapped in a `Some(T)`. + /// But if the iteration is over, `None` is returned. /// /// [`next()`]: trait.Iterator.html#tymethod.next /// - /// Because `peek()` returns reference, and many iterators iterate over - /// references, this leads to a possibly confusing situation where the + /// Because `peek()` returns a reference, and many iterators iterate over + /// references, there can be a possibly confusing situation where the /// return value is a double reference. You can see this effect in the - /// examples below, with `&&i32`. + /// examples below. /// /// # Examples /// @@ -1075,13 +1073,13 @@ impl Peekable { /// /// assert_eq!(iter.next(), Some(&2)); /// - /// // we can peek() multiple times, the iterator won't advance + /// // The iterator does not advance even if we `peek` multiple times /// assert_eq!(iter.peek(), Some(&&3)); /// assert_eq!(iter.peek(), Some(&&3)); /// /// assert_eq!(iter.next(), Some(&3)); /// - /// // after the iterator is finished, so is peek() + /// // After the iterator is finished, so is `peek()` /// assert_eq!(iter.peek(), None); /// assert_eq!(iter.next(), None); /// ``` @@ -1113,10 +1111,10 @@ impl Peekable { /// /// let mut iter = xs.iter().peekable(); /// - /// // there are still elements to iterate over + /// // There are still elements to iterate over /// assert_eq!(iter.is_empty(), false); /// - /// // let's consume the iterator + /// // Let's consume the iterator /// iter.next(); /// iter.next(); /// iter.next(); From 170df14e6223a4583d5d88bac04434b2491aacb3 Mon Sep 17 00:00:00 2001 From: Oliver Middleton Date: Tue, 14 Jun 2016 21:23:21 +0100 Subject: [PATCH 07/24] Add/improve num const docs This adds short summaries to all num consts. --- src/libcore/num/f32.rs | 60 +++++++++++++++++----------------- src/libcore/num/f64.rs | 60 +++++++++++++++++----------------- src/libcore/num/int_macros.rs | 4 +-- src/libcore/num/mod.rs | 1 - src/libcore/num/uint_macros.rs | 4 +-- 5 files changed, 64 insertions(+), 65 deletions(-) diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index c24eaa3eabc75..0caa27f21dc3b 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -20,53 +20,53 @@ use mem; use num::Float; use num::FpCategory as Fp; +/// The radix or base of the internal representation of `f32`. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const RADIX: u32 = 2; +/// Number of significant digits in base 2. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MANTISSA_DIGITS: u32 = 24; +/// Approximate number of significant digits in base 10. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const DIGITS: u32 = 6; +/// A very small number. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const EPSILON: f32 = 1.19209290e-07_f32; -/// Smallest finite f32 value +/// Smallest finite `f32` value. #[stable(feature = "rust1", since = "1.0.0")] pub const MIN: f32 = -3.40282347e+38_f32; -/// Smallest positive, normalized f32 value +/// Smallest positive normal `f32` value. #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_POSITIVE: f32 = 1.17549435e-38_f32; -/// Largest finite f32 value +/// Largest finite `f32` value. #[stable(feature = "rust1", since = "1.0.0")] pub const MAX: f32 = 3.40282347e+38_f32; +/// Minimum possible normal power of 2 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MIN_EXP: i32 = -125; +/// Maximum possible power of 2 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MAX_EXP: i32 = 128; +/// Minimum possible normal power of 10 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MIN_10_EXP: i32 = -37; +/// Maximum possible power of 10 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MAX_10_EXP: i32 = 38; +/// Not a Number (NaN). #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const NAN: f32 = 0.0_f32/0.0_f32; +/// Infinity (∞). #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const INFINITY: f32 = 1.0_f32/0.0_f32; +/// Negative infinity (-∞). #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const NEG_INFINITY: f32 = -1.0_f32/0.0_f32; /// Basic mathematical constants. @@ -74,67 +74,67 @@ pub const NEG_INFINITY: f32 = -1.0_f32/0.0_f32; pub mod consts { // FIXME: replace with mathematical constants from cmath. - /// Archimedes' constant + /// Archimedes' constant (π) #[stable(feature = "rust1", since = "1.0.0")] pub const PI: f32 = 3.14159265358979323846264338327950288_f32; - /// pi/2.0 + /// π/2 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_2: f32 = 1.57079632679489661923132169163975144_f32; - /// pi/3.0 + /// π/3 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_3: f32 = 1.04719755119659774615421446109316763_f32; - /// pi/4.0 + /// π/4 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_4: f32 = 0.785398163397448309615660845819875721_f32; - /// pi/6.0 + /// π/6 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_6: f32 = 0.52359877559829887307710723054658381_f32; - /// pi/8.0 + /// π/8 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_8: f32 = 0.39269908169872415480783042290993786_f32; - /// 1.0/pi + /// 1/π #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_1_PI: f32 = 0.318309886183790671537767526745028724_f32; - /// 2.0/pi + /// 2/π #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_2_PI: f32 = 0.636619772367581343075535053490057448_f32; - /// 2.0/sqrt(pi) + /// 2/sqrt(π) #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_2_SQRT_PI: f32 = 1.12837916709551257389615890312154517_f32; - /// sqrt(2.0) + /// sqrt(2) #[stable(feature = "rust1", since = "1.0.0")] pub const SQRT_2: f32 = 1.41421356237309504880168872420969808_f32; - /// 1.0/sqrt(2.0) + /// 1/sqrt(2) #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_1_SQRT_2: f32 = 0.707106781186547524400844362104849039_f32; - /// Euler's number + /// Euler's number (e) #[stable(feature = "rust1", since = "1.0.0")] pub const E: f32 = 2.71828182845904523536028747135266250_f32; - /// log2(e) + /// log2(e) #[stable(feature = "rust1", since = "1.0.0")] pub const LOG2_E: f32 = 1.44269504088896340735992468100189214_f32; - /// log10(e) + /// log10(e) #[stable(feature = "rust1", since = "1.0.0")] pub const LOG10_E: f32 = 0.434294481903251827651128918916605082_f32; - /// ln(2.0) + /// ln(2) #[stable(feature = "rust1", since = "1.0.0")] pub const LN_2: f32 = 0.693147180559945309417232121458176568_f32; - /// ln(10.0) + /// ln(10) #[stable(feature = "rust1", since = "1.0.0")] pub const LN_10: f32 = 2.30258509299404568401799145468436421_f32; } diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs index beeee80902525..766e83a895378 100644 --- a/src/libcore/num/f64.rs +++ b/src/libcore/num/f64.rs @@ -20,53 +20,53 @@ use mem; use num::FpCategory as Fp; use num::Float; +/// The radix or base of the internal representation of `f64`. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const RADIX: u32 = 2; +/// Number of significant digits in base 2. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MANTISSA_DIGITS: u32 = 53; +/// Approximate number of significant digits in base 10. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const DIGITS: u32 = 15; +/// A very small number. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const EPSILON: f64 = 2.2204460492503131e-16_f64; -/// Smallest finite f64 value +/// Smallest finite `f64` value. #[stable(feature = "rust1", since = "1.0.0")] pub const MIN: f64 = -1.7976931348623157e+308_f64; -/// Smallest positive, normalized f64 value +/// Smallest positive normal `f64` value. #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_POSITIVE: f64 = 2.2250738585072014e-308_f64; -/// Largest finite f64 value +/// Largest finite `f64` value. #[stable(feature = "rust1", since = "1.0.0")] pub const MAX: f64 = 1.7976931348623157e+308_f64; +/// Minimum possible normal power of 2 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MIN_EXP: i32 = -1021; +/// Maximum possible power of 2 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MAX_EXP: i32 = 1024; +/// Minimum possible normal power of 10 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MIN_10_EXP: i32 = -307; +/// Maximum possible power of 10 exponent. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MAX_10_EXP: i32 = 308; +/// Not a Number (NaN). #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const NAN: f64 = 0.0_f64/0.0_f64; +/// Infinity (∞). #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const INFINITY: f64 = 1.0_f64/0.0_f64; +/// Negative infinity (-∞). #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const NEG_INFINITY: f64 = -1.0_f64/0.0_f64; /// Basic mathematical constants. @@ -74,67 +74,67 @@ pub const NEG_INFINITY: f64 = -1.0_f64/0.0_f64; pub mod consts { // FIXME: replace with mathematical constants from cmath. - /// Archimedes' constant + /// Archimedes' constant (π) #[stable(feature = "rust1", since = "1.0.0")] pub const PI: f64 = 3.14159265358979323846264338327950288_f64; - /// pi/2.0 + /// π/2 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_2: f64 = 1.57079632679489661923132169163975144_f64; - /// pi/3.0 + /// π/3 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_3: f64 = 1.04719755119659774615421446109316763_f64; - /// pi/4.0 + /// π/4 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_4: f64 = 0.785398163397448309615660845819875721_f64; - /// pi/6.0 + /// π/6 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_6: f64 = 0.52359877559829887307710723054658381_f64; - /// pi/8.0 + /// π/8 #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_PI_8: f64 = 0.39269908169872415480783042290993786_f64; - /// 1.0/pi + /// 1/π #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_1_PI: f64 = 0.318309886183790671537767526745028724_f64; - /// 2.0/pi + /// 2/π #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_2_PI: f64 = 0.636619772367581343075535053490057448_f64; - /// 2.0/sqrt(pi) + /// 2/sqrt(π) #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_2_SQRT_PI: f64 = 1.12837916709551257389615890312154517_f64; - /// sqrt(2.0) + /// sqrt(2) #[stable(feature = "rust1", since = "1.0.0")] pub const SQRT_2: f64 = 1.41421356237309504880168872420969808_f64; - /// 1.0/sqrt(2.0) + /// 1/sqrt(2) #[stable(feature = "rust1", since = "1.0.0")] pub const FRAC_1_SQRT_2: f64 = 0.707106781186547524400844362104849039_f64; - /// Euler's number + /// Euler's number (e) #[stable(feature = "rust1", since = "1.0.0")] pub const E: f64 = 2.71828182845904523536028747135266250_f64; - /// log2(e) + /// log2(e) #[stable(feature = "rust1", since = "1.0.0")] pub const LOG2_E: f64 = 1.44269504088896340735992468100189214_f64; - /// log10(e) + /// log10(e) #[stable(feature = "rust1", since = "1.0.0")] pub const LOG10_E: f64 = 0.434294481903251827651128918916605082_f64; - /// ln(2.0) + /// ln(2) #[stable(feature = "rust1", since = "1.0.0")] pub const LN_2: f64 = 0.693147180559945309417232121458176568_f64; - /// ln(10.0) + /// ln(10) #[stable(feature = "rust1", since = "1.0.0")] pub const LN_10: f64 = 2.30258509299404568401799145468436421_f64; } diff --git a/src/libcore/num/int_macros.rs b/src/libcore/num/int_macros.rs index bd6cfc427affd..e74c30d5e5af8 100644 --- a/src/libcore/num/int_macros.rs +++ b/src/libcore/num/int_macros.rs @@ -12,11 +12,11 @@ macro_rules! int_module { ($T:ident, $bits:expr) => ( +/// The smallest value that can be represented by this integer type. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MIN: $T = $T::min_value(); +/// The largest value that can be represented by this integer type. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MAX: $T = $T::max_value(); ) } diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs index 883e9206dde1d..2d6f7afb22e9f 100644 --- a/src/libcore/num/mod.rs +++ b/src/libcore/num/mod.rs @@ -11,7 +11,6 @@ //! Numeric traits and functions for the built-in numeric types. #![stable(feature = "rust1", since = "1.0.0")] -#![allow(missing_docs)] use char::CharExt; use cmp::PartialOrd; diff --git a/src/libcore/num/uint_macros.rs b/src/libcore/num/uint_macros.rs index 2ab2f9548ef1b..cc9256ab6bf4e 100644 --- a/src/libcore/num/uint_macros.rs +++ b/src/libcore/num/uint_macros.rs @@ -12,11 +12,11 @@ macro_rules! uint_module { ($T:ident, $bits:expr) => ( +/// The smallest value that can be represented by this integer type. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MIN: $T = $T::min_value(); +/// The largest value that can be represented by this integer type. #[stable(feature = "rust1", since = "1.0.0")] -#[allow(missing_docs)] pub const MAX: $T = $T::max_value(); ) } From 60e19ce9e60ae054d1c468d1a4385bad3fbb8f63 Mon Sep 17 00:00:00 2001 From: Nick Cameron Date: Fri, 17 Jun 2016 15:14:25 +0100 Subject: [PATCH 08/24] save-analysis: fix a bug with tuple sub-expressions --- src/librustc_save_analysis/dump_visitor.rs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/librustc_save_analysis/dump_visitor.rs b/src/librustc_save_analysis/dump_visitor.rs index 56c7436a8fe5c..906c3e87a6d99 100644 --- a/src/librustc_save_analysis/dump_visitor.rs +++ b/src/librustc_save_analysis/dump_visitor.rs @@ -29,6 +29,7 @@ use rustc::hir::def::Def; use rustc::hir::def_id::DefId; +use rustc::hir::map::Node; use rustc::session::Session; use rustc::ty::{self, TyCtxt, ImplOrTraitItem, ImplOrTraitItemContainer}; @@ -1297,7 +1298,14 @@ impl<'v, 'l, 'tcx: 'l, 'll, D: Dump +'ll> Visitor<'v> for DumpVisitor<'l, 'tcx, ast::ExprKind::TupField(ref sub_ex, idx) => { self.visit_expr(&sub_ex); - let hir_node = self.save_ctxt.tcx.map.expect_expr(sub_ex.id); + let hir_node = match self.save_ctxt.tcx.map.find(sub_ex.id) { + Some(Node::NodeExpr(expr)) => expr, + _ => { + debug!("Missing or weird node for sub-expression {} in {:?}", + sub_ex.id, ex); + return; + } + }; let ty = &self.tcx.expr_ty_adjusted(&hir_node).sty; match *ty { ty::TyStruct(def, _) => { From ad7d7eaba3f6be5b2e4fa388d99ab4aa780773b3 Mon Sep 17 00:00:00 2001 From: Andre Bogus Date: Tue, 28 Jun 2016 12:32:45 +0200 Subject: [PATCH 09/24] extend+improve HIR types documentation --- src/librustc/hir/mod.rs | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/src/librustc/hir/mod.rs b/src/librustc/hir/mod.rs index a139dd152f006..9caf0791398c4 100644 --- a/src/librustc/hir/mod.rs +++ b/src/librustc/hir/mod.rs @@ -836,7 +836,7 @@ pub enum Expr_ { ExprVec(HirVec>), /// A function call /// - /// The first field resolves to the function itself, + /// The first field resolves to the function itself (usually an `ExprPath`), /// and the second field is the list of arguments ExprCall(P, HirVec>), /// A method call (`x.foo::(a, b, c, d)`) @@ -845,9 +845,9 @@ pub enum Expr_ { /// The vector of `Ty`s are the ascripted type parameters for the method /// (within the angle brackets). /// - /// The first element of the vector of `Expr`s is the expression that evaluates - /// to the object on which the method is being called on (the receiver), - /// and the remaining elements are the rest of the arguments. + /// The first element of the vector of `Expr`s is the expression that + /// evaluates to the object on which the method is being called on (the + /// receiver), and the remaining elements are the rest of the arguments. /// /// Thus, `x.foo::(a, b, c, d)` is represented as /// `ExprMethodCall(foo, [Bar, Baz], [x, a, b, c, d])`. @@ -919,13 +919,13 @@ pub enum Expr_ { /// Inline assembly (from `asm!`), with its outputs and inputs. ExprInlineAsm(InlineAsm, Vec>, Vec>), - /// A struct literal expression. + /// A struct or enum variant literal expression. /// /// For example, `Foo {x: 1, y: 2}`, or /// `Foo {x: 1, .. base}`, where `base` is the `Option`. ExprStruct(Path, HirVec, Option>), - /// A vector literal constructed from one repeated element. + /// An array literal constructed from one repeated element. /// /// For example, `[1; 5]`. The first expression is the element /// to be repeated; the second is the number of times to repeat it. @@ -950,14 +950,21 @@ pub struct QSelf { pub position: usize, } +/// Hints at the original code for a `match _ { .. }` #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug, Copy)] pub enum MatchSource { + /// A `match _ { .. }` Normal, + /// An `if let _ = _ { .. }` (optionally with `else { .. }` IfLetDesugar { contains_else_clause: bool, }, + /// A `while let _ = _ { .. }` (which was desugared to a + /// `loop { match _ { .. } }` WhileLetDesugar, + /// A desugared `for _ in _ { .. }` loop ForLoopDesugar, + /// A desugared `?` operator TryDesugar, } @@ -975,8 +982,7 @@ pub struct MutTy { pub mutbl: Mutability, } -/// Represents a method's signature in a trait declaration, -/// or in an implementation. +/// Represents a method's signature in a trait declaration or implementation. #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)] pub struct MethodSig { pub unsafety: Unsafety, @@ -999,13 +1005,20 @@ pub struct TraitItem { pub span: Span, } +/// Represents a trait method or associated constant or type #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)] pub enum TraitItem_ { + /// An associated constant with an optional value (otherwise `impl`s + /// must contain a value) ConstTraitItem(P, Option>), + /// A method with an optional body MethodTraitItem(MethodSig, Option>), + /// An associated type with (possibly empty) bounds and optional concrete + /// type TypeTraitItem(TyParamBounds, Option>), } +/// Represents anything within an `impl` block #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)] pub struct ImplItem { pub id: NodeId, @@ -1017,10 +1030,15 @@ pub struct ImplItem { pub span: Span, } +/// Represents different contents within `impl`s #[derive(Clone, PartialEq, Eq, RustcEncodable, RustcDecodable, Hash, Debug)] pub enum ImplItemKind { + /// An associated constant of the given type, set to the constant result + /// of the expression Const(P, P), + /// A method implementation with the given signature and body Method(MethodSig, P), + /// An associated type Type(P), } From 5de684adf6f6b21a6ff56953a63012e15ea4f6d4 Mon Sep 17 00:00:00 2001 From: Andre Bogus Date: Tue, 28 Jun 2016 18:07:39 +0200 Subject: [PATCH 10/24] adressed @eddyb's comments --- src/librustc/hir/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/librustc/hir/mod.rs b/src/librustc/hir/mod.rs index 9caf0791398c4..e1e681b7aff35 100644 --- a/src/librustc/hir/mod.rs +++ b/src/librustc/hir/mod.rs @@ -919,7 +919,7 @@ pub enum Expr_ { /// Inline assembly (from `asm!`), with its outputs and inputs. ExprInlineAsm(InlineAsm, Vec>, Vec>), - /// A struct or enum variant literal expression. + /// A struct or struct-like variant literal expression. /// /// For example, `Foo {x: 1, y: 2}`, or /// `Foo {x: 1, .. base}`, where `base` is the `Option`. @@ -955,12 +955,12 @@ pub struct QSelf { pub enum MatchSource { /// A `match _ { .. }` Normal, - /// An `if let _ = _ { .. }` (optionally with `else { .. }` + /// An `if let _ = _ { .. }` (optionally with `else { .. }`) IfLetDesugar { contains_else_clause: bool, }, /// A `while let _ = _ { .. }` (which was desugared to a - /// `loop { match _ { .. } }` + /// `loop { match _ { .. } }`) WhileLetDesugar, /// A desugared `for _ in _ { .. }` loop ForLoopDesugar, From 3f6c38c5e00b5c5241498d63897a16223018da3b Mon Sep 17 00:00:00 2001 From: "decauwsemaecker.glen@gmail.com" Date: Wed, 29 Jun 2016 12:43:57 -0500 Subject: [PATCH 11/24] propagate rustbuild's bootstrap.py '--help' flag --- src/bootstrap/bootstrap.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bootstrap/bootstrap.py b/src/bootstrap/bootstrap.py index 7b0a5d6b6dfc4..56bc9662bc2b1 100644 --- a/src/bootstrap/bootstrap.py +++ b/src/bootstrap/bootstrap.py @@ -346,7 +346,7 @@ def main(): parser.add_argument('--clean', action='store_true') parser.add_argument('-v', '--verbose', action='store_true') - args = [a for a in sys.argv if a != '-h'] + args = [a for a in sys.argv if a != '-h' and a != '--help'] args, _ = parser.parse_known_args(args) # Configure initial bootstrap From 2dcfa628768af55b07931c8717e92ddf2f70940d Mon Sep 17 00:00:00 2001 From: Oliver Middleton Date: Thu, 30 Jun 2016 08:30:30 +0100 Subject: [PATCH 12/24] Correct MIN_EXP docs and improve EPSILON --- src/libcore/num/f32.rs | 4 ++-- src/libcore/num/f64.rs | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index 0caa27f21dc3b..c408b10c399f7 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -31,7 +31,7 @@ pub const MANTISSA_DIGITS: u32 = 24; #[stable(feature = "rust1", since = "1.0.0")] pub const DIGITS: u32 = 6; -/// A very small number. +/// Difference between `1.0` and the next largest representable number. #[stable(feature = "rust1", since = "1.0.0")] pub const EPSILON: f32 = 1.19209290e-07_f32; @@ -45,7 +45,7 @@ pub const MIN_POSITIVE: f32 = 1.17549435e-38_f32; #[stable(feature = "rust1", since = "1.0.0")] pub const MAX: f32 = 3.40282347e+38_f32; -/// Minimum possible normal power of 2 exponent. +/// One greater than the minimum possible normal power of 2 exponent. #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_EXP: i32 = -125; /// Maximum possible power of 2 exponent. diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs index 766e83a895378..006e9d1264d7c 100644 --- a/src/libcore/num/f64.rs +++ b/src/libcore/num/f64.rs @@ -31,7 +31,7 @@ pub const MANTISSA_DIGITS: u32 = 53; #[stable(feature = "rust1", since = "1.0.0")] pub const DIGITS: u32 = 15; -/// A very small number. +/// Difference between `1.0` and the next largest representable number. #[stable(feature = "rust1", since = "1.0.0")] pub const EPSILON: f64 = 2.2204460492503131e-16_f64; @@ -45,7 +45,7 @@ pub const MIN_POSITIVE: f64 = 2.2250738585072014e-308_f64; #[stable(feature = "rust1", since = "1.0.0")] pub const MAX: f64 = 1.7976931348623157e+308_f64; -/// Minimum possible normal power of 2 exponent. +/// One greater than the minimum possible normal power of 2 exponent. #[stable(feature = "rust1", since = "1.0.0")] pub const MIN_EXP: i32 = -1021; /// Maximum possible power of 2 exponent. From bdea7054653237c06be48643430e318dedb61ca5 Mon Sep 17 00:00:00 2001 From: Hariharan R Date: Sat, 2 Jul 2016 20:36:41 +0530 Subject: [PATCH 13/24] update cargo doc link updated proper link of cargo doc that contains details about list of options available in semantic versioninig for the dependencies section in Cargo.toml --- src/doc/book/guessing-game.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index c759ff9bdbde4..6ce75efd1031d 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -370,7 +370,7 @@ We could also use a range of versions. [Cargo’s documentation][cargodoc] contains more details. [semver]: http://semver.org -[cargodoc]: http://doc.crates.io/crates-io.html +[cargodoc]: http://doc.crates.io/specifying-dependencies.html Now, without changing any of our code, let’s build our project: From c6a04d9ba44d98de58dff18684463ce9d9b2b22d Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sat, 2 Jul 2016 20:15:28 -0400 Subject: [PATCH 14/24] Fix broken markdown link in README. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9463b0e849856..384795608db76 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ build. [MSYS2][msys2] can be used to easily build Rust on Windows: -msys2: https://msys2.github.io/ +[msys2]: https://msys2.github.io/ 1. Grab the latest [MSYS2 installer][msys2] and go through the installer. From df93e1841864140ecb528c93948a8c164ae3f3c1 Mon Sep 17 00:00:00 2001 From: Kaivo Anastetiks Date: Sat, 2 Jul 2016 20:39:21 -0400 Subject: [PATCH 15/24] Clarifies the meaning of the external mutability. --- src/doc/book/mutability.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/mutability.md b/src/doc/book/mutability.md index e462715114624..35a286a0d311a 100644 --- a/src/doc/book/mutability.md +++ b/src/doc/book/mutability.md @@ -62,8 +62,8 @@ Note that here, the `x` is mutable, but not the `y`. # Interior vs. Exterior Mutability However, when we say something is ‘immutable’ in Rust, that doesn’t mean that -it’s not able to be changed: we mean something has ‘exterior mutability’. Consider, -for example, [`Arc`][arc]: +it’s not able to be changed: we are referring to it's ‘exterior mutability’ that +in this case is immutable. Consider, for example, [`Arc`][arc]: ```rust use std::sync::Arc; From 5dfd79a8e624670f041e648ec2ac140699ea5322 Mon Sep 17 00:00:00 2001 From: Jared Manning Date: Sun, 3 Jul 2016 03:01:18 -0500 Subject: [PATCH 16/24] Fix spacing in for loop enumeration example Add a space between the comma and j in (i, j) to make it look nice. --- src/doc/book/loops.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/loops.md b/src/doc/book/loops.md index e23e6f3a786a5..e681d1bee0618 100644 --- a/src/doc/book/loops.md +++ b/src/doc/book/loops.md @@ -105,7 +105,7 @@ When you need to keep track of how many times you already looped, you can use th #### On ranges: ```rust -for (i,j) in (5..10).enumerate() { +for (i, j) in (5..10).enumerate() { println!("i = {} and j = {}", i, j); } ``` From 872d107dea229fdeaae2cf3d904fb348d6f75dde Mon Sep 17 00:00:00 2001 From: Sylvestre Ledru Date: Sun, 3 Jul 2016 10:00:52 +0200 Subject: [PATCH 17/24] Fix a few typos in the code --- src/librustdoc/html/highlight.rs | 2 +- src/librustdoc/html/render.rs | 2 +- src/libstd/memchr.rs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/librustdoc/html/highlight.rs b/src/librustdoc/html/highlight.rs index 2e2f99897733d..70447bf35881f 100644 --- a/src/librustdoc/html/highlight.rs +++ b/src/librustdoc/html/highlight.rs @@ -107,7 +107,7 @@ pub enum Class { /// /// The classifier will call into the `Writer` implementation as it finds spans /// of text to highlight. Exactly how that text should be highlighted is up to -/// the implemention. +/// the implementation. pub trait Writer { /// Called when we start processing a span of text that should be highlighted. /// The `Class` argument specifies how it should be highlighted. diff --git a/src/librustdoc/html/render.rs b/src/librustdoc/html/render.rs index 9f2b33c0282ed..bc1984827c6d7 100644 --- a/src/librustdoc/html/render.rs +++ b/src/librustdoc/html/render.rs @@ -2721,7 +2721,7 @@ impl<'a> fmt::Display for Sidebar<'a> { let parentlen = cx.current.len() - if it.is_mod() {1} else {0}; // the sidebar is designed to display sibling functions, modules and - // other miscellaneous informations. since there are lots of sibling + // other miscellaneous information. since there are lots of sibling // items (and that causes quadratic growth in large modules), // we refactor common parts into a shared JavaScript file per module. // still, we don't move everything into JS because we want to preserve diff --git a/src/libstd/memchr.rs b/src/libstd/memchr.rs index 1d97611eabb26..a408b4378e19e 100644 --- a/src/libstd/memchr.rs +++ b/src/libstd/memchr.rs @@ -239,7 +239,7 @@ mod fallback { text[..offset].iter().rposition(|elt| *elt == x) } - // test fallback implementations on all plattforms + // test fallback implementations on all platforms #[test] fn matches_one() { assert_eq!(Some(0), memchr(b'a', b"a")); From 3fcb64927750b8c4bccd866ec137500de2e7aea3 Mon Sep 17 00:00:00 2001 From: Sylvestre Ledru Date: Sun, 3 Jul 2016 10:00:19 +0200 Subject: [PATCH 18/24] Fix a few typos in the doc --- src/doc/book/closures.md | 4 ++-- src/doc/book/testing.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/book/closures.md b/src/doc/book/closures.md index a6b4e9492181c..e8c88b7db0699 100644 --- a/src/doc/book/closures.md +++ b/src/doc/book/closures.md @@ -339,7 +339,7 @@ fn call_with_ref<'a, F>(some_closure:F) -> i32 where F: Fn(&'a 32) -> i32 { ``` -However this presents a problem with in our case. When you specify the explict +However this presents a problem with in our case. When you specify the explicit lifetime on a function it binds that lifetime to the *entire* scope of the function instead of just the invocation scope of our closure. This means that the borrow checker will see a mutable reference in the same lifetime as our immutable reference and fail @@ -354,7 +354,7 @@ fn call_with_ref(some_closure:F) -> i32 ``` This lets the Rust compiler find the minimum lifetime to invoke our closure and -satisfy the borrow checker's rules. Our function then compiles and excutes as we +satisfy the borrow checker's rules. Our function then compiles and executes as we expect. ```rust diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md index 7954085472e50..86729147ed065 100644 --- a/src/doc/book/testing.md +++ b/src/doc/book/testing.md @@ -431,7 +431,7 @@ one. Cargo will ignore files in subdirectories of the `tests/` directory. Therefore shared modules in integrations tests are possible. -For example `tests/common/mod.rs` is not seperatly compiled by cargo but can +For example `tests/common/mod.rs` is not separately compiled by cargo but can be imported in every test with `mod common;` That's all there is to the `tests` directory. The `tests` module isn't needed From 5efc780e146f51a87b1137adb116c825d87e07a3 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 3 Jul 2016 22:03:45 +0200 Subject: [PATCH 19/24] doc: fix and shorten comment --- src/librustc_resolve/lib.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/librustc_resolve/lib.rs b/src/librustc_resolve/lib.rs index ed400af66855a..18f2dbb23b2b1 100644 --- a/src/librustc_resolve/lib.rs +++ b/src/librustc_resolve/lib.rs @@ -2892,8 +2892,7 @@ impl<'a> Resolver<'a> { if !msg.is_empty() { msg = format!(". Did you mean {}?", msg); } else { - // we check if this a module and if so, we display a help - // message + // we display a help message if this is a module let name_path = path.segments.iter() .map(|seg| seg.identifier.name) .collect::>(); From 6a85183e6f7c29777e1058a88f328e05137abb4d Mon Sep 17 00:00:00 2001 From: Kaivo Anastetiks Date: Tue, 5 Jul 2016 07:26:38 -0400 Subject: [PATCH 20/24] Replace it's by its. --- src/doc/book/mutability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/mutability.md b/src/doc/book/mutability.md index 35a286a0d311a..a0a49d55e1057 100644 --- a/src/doc/book/mutability.md +++ b/src/doc/book/mutability.md @@ -62,7 +62,7 @@ Note that here, the `x` is mutable, but not the `y`. # Interior vs. Exterior Mutability However, when we say something is ‘immutable’ in Rust, that doesn’t mean that -it’s not able to be changed: we are referring to it's ‘exterior mutability’ that +it’s not able to be changed: we are referring to its ‘exterior mutability’ that in this case is immutable. Consider, for example, [`Arc`][arc]: ```rust From 1d9284664fdd6aa9ffe801ccd768949fa813223d Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 5 Jul 2016 08:34:58 -0700 Subject: [PATCH 21/24] Bump version to 1.12.0 Beta's now in the forge, let's start working on 1.12.0! --- mk/main.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mk/main.mk b/mk/main.mk index daf656f89c1a5..4c72597f0c5c1 100644 --- a/mk/main.mk +++ b/mk/main.mk @@ -13,7 +13,7 @@ ###################################################################### # The version number -CFG_RELEASE_NUM=1.11.0 +CFG_RELEASE_NUM=1.12.0 # An optional number to put after the label, e.g. '.2' -> '-beta.2' # NB Make sure it starts with a dot to conform to semver pre-release From 159d1ab540cd53f1e63db0e00a50180d535a8bce Mon Sep 17 00:00:00 2001 From: Kaivo Anastetiks Date: Tue, 5 Jul 2016 13:17:16 -0400 Subject: [PATCH 22/24] Add a section about crate documentation. --- src/doc/book/documentation.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md index 3c6643fbfe155..6292ba9aac403 100644 --- a/src/doc/book/documentation.md +++ b/src/doc/book/documentation.md @@ -486,6 +486,17 @@ you have a module in `foo.rs`, you'll often open its code and see this: //! The `foo` module contains a lot of useful functionality blah blah blah ``` +### Crate documentation + +Crates can be documented by placing an inner doc comment (`//!`) at the +beginning of the crate root, aka `lib.rs`: + +```rust +//! This is documentation for the `foo` crate. +//! +//! The foo crate is meant to be used for bar. +``` + ### Documentation comment style Check out [RFC 505][rfc505] for full conventions around the style and format of From 74e96299a22ef1629d7ea8268815fc2b82c7e194 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 5 Jul 2016 13:46:06 -0400 Subject: [PATCH 23/24] show both forms of empty struct declaration --- src/doc/book/structs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 1fb74e33a622f..328db25b819d8 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -234,9 +234,12 @@ rather than positions. You can define a `struct` with no members at all: ```rust -struct Electron {} +struct Electron {} // use empty braces... +struct Proton; // ...or just a semicolon +// whether you declared the struct with braces or not, do the same when creating one let x = Electron {}; +let y = Proton; ``` Such a `struct` is called ‘unit-like’ because it resembles the empty From b467c003c61ffc30cb145db157442a583d363382 Mon Sep 17 00:00:00 2001 From: ggomez Date: Wed, 6 Jul 2016 18:12:24 +0200 Subject: [PATCH 24/24] Remove invalid CSS rule for doc titles --- src/librustdoc/html/static/rustdoc.css | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/librustdoc/html/static/rustdoc.css b/src/librustdoc/html/static/rustdoc.css index b45e059e6d5e9..303cc671f4a23 100644 --- a/src/librustdoc/html/static/rustdoc.css +++ b/src/librustdoc/html/static/rustdoc.css @@ -572,14 +572,6 @@ a.test-arrow { right: 5px; } -.methods .section-header { - /* Override parent class attributes. */ - border-bottom: none !important; - font-size: 1.1em !important; - margin: 0 0 -5px; - padding: 0; -} - .section-header:hover a:after { content: '\2002\00a7\2002'; }