From 993f13a2cf125610dc6a34bf68aa6afd87a723d6 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Wed, 27 Apr 2016 23:29:49 -0400 Subject: [PATCH 01/22] 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/22] 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/22] "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/22] 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/22] 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 170df14e6223a4583d5d88bac04434b2491aacb3 Mon Sep 17 00:00:00 2001 From: Oliver Middleton Date: Tue, 14 Jun 2016 21:23:21 +0100 Subject: [PATCH 06/22] 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 ad7d7eaba3f6be5b2e4fa388d99ab4aa780773b3 Mon Sep 17 00:00:00 2001 From: Andre Bogus Date: Tue, 28 Jun 2016 12:32:45 +0200 Subject: [PATCH 07/22] 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 08/22] 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 09/22] 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 10/22] 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 a0e01cc3700970bc996aaaf3fdf57f704bacf33e Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sat, 2 Jul 2016 09:50:19 -0400 Subject: [PATCH 11/22] Add doc examples for `io::Error::from_raw_os_error`. --- src/libstd/io/error.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/libstd/io/error.rs b/src/libstd/io/error.rs index e142c78569bd7..f410bc3b147b8 100644 --- a/src/libstd/io/error.rs +++ b/src/libstd/io/error.rs @@ -214,6 +214,30 @@ impl Error { } /// Creates a new instance of an `Error` from a particular OS error code. + /// + /// # Examples + /// + /// On Unix: + /// + /// ``` + /// # if cfg!(unix) { + /// use std::io; + /// + /// let error = io::Error::from_raw_os_error(98); + /// assert_eq!(error.kind(), io::ErrorKind::AddrInUse); + /// # } + /// ``` + /// + /// On Windows: + /// + /// ``` + /// # if cfg!(windows) { + /// use std::io; + /// + /// let error = io::Error::from_raw_os_error(10048); + /// assert_eq!(error.kind(), io::ErrorKind::AddrInUse); + /// # } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn from_raw_os_error(code: i32) -> Error { Error { repr: Repr::Os(code) } From bdea7054653237c06be48643430e318dedb61ca5 Mon Sep 17 00:00:00 2001 From: Hariharan R Date: Sat, 2 Jul 2016 20:36:41 +0530 Subject: [PATCH 12/22] 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 13/22] 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 14/22] 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 15/22] 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 16/22] 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 17/22] 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 18/22] 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 19/22] 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 6109ef5c74eb498391d8effe73159103fb761bdc Mon Sep 17 00:00:00 2001 From: ggomez Date: Tue, 5 Jul 2016 11:36:43 +0200 Subject: [PATCH 20/22] Fix `std::path::Path::file_name()` doc --- src/libstd/path.rs | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index ad4cdef615847..c5633f254207c 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1529,8 +1529,7 @@ impl Path { /// The final component of the path, if it is a normal file. /// - /// If the path terminates in `.`, `..`, or consists solely of a root of - /// prefix, `file_name` will return `None`. + /// If the path terminates in `..`, `file_name` will return `None`. /// /// # Examples /// @@ -1543,6 +1542,14 @@ impl Path { /// /// assert_eq!(Some(os_str), path.file_name()); /// ``` + /// + /// # Other examples + /// + /// ``` + /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.").file_name()); + /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.//").file_name()); + /// assert_eq!(None, Path::new("foo.txt/..").file_name()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn file_name(&self) -> Option<&OsStr> { self.components().next_back().and_then(|p| { From 159d1ab540cd53f1e63db0e00a50180d535a8bce Mon Sep 17 00:00:00 2001 From: Kaivo Anastetiks Date: Tue, 5 Jul 2016 13:17:16 -0400 Subject: [PATCH 21/22] 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 22/22] 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