From cb1e6a2dc4f5ceba68b52f7d088a9e571948f765 Mon Sep 17 00:00:00 2001 From: Dan Callahan Date: Fri, 3 Apr 2015 22:38:30 -0500 Subject: [PATCH 01/10] book: use `mod test` consistently Fixes #24030 Of the four code samples with modules in TRPL: - 2 use `mod test` - 2 use `mod tests` We should be consistent here, but which is right? The stdlib is split: $ grep -r 'mod tests {' src/lib* | wc -l 63 $ grep -r 'mod test {' src/lib* | wc -l 58 Subjectively, I like the plural, but both the language reference and the style guide recommend the singular. So we'll go with that here, for now. --- src/doc/trpl/benchmark-tests.md | 2 +- src/doc/trpl/testing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/benchmark-tests.md b/src/doc/trpl/benchmark-tests.md index 88796537593..890a2f8ae7d 100644 --- a/src/doc/trpl/benchmark-tests.md +++ b/src/doc/trpl/benchmark-tests.md @@ -13,7 +13,7 @@ pub fn add_two(a: i32) -> i32 { } #[cfg(test)] -mod tests { +mod test { use super::*; use test::Bencher; diff --git a/src/doc/trpl/testing.md b/src/doc/trpl/testing.md index fddb4c19031..8cf126cad95 100644 --- a/src/doc/trpl/testing.md +++ b/src/doc/trpl/testing.md @@ -382,7 +382,7 @@ pub fn add_two(a: i32) -> i32 { } #[cfg(test)] -mod tests { +mod test { use super::*; #[test] From 48a023c2e946f6df4217c62be71313484e673c40 Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Sat, 4 Apr 2015 05:54:28 -0400 Subject: [PATCH 02/10] Convert lifetime shadowing into a hard error, as promised. --- src/librustc/middle/resolve_lifetime.rs | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/librustc/middle/resolve_lifetime.rs b/src/librustc/middle/resolve_lifetime.rs index a3d71c989bf..1036c97a5ad 100644 --- a/src/librustc/middle/resolve_lifetime.rs +++ b/src/librustc/middle/resolve_lifetime.rs @@ -507,7 +507,7 @@ impl<'a> LifetimeContext<'a> { EarlyScope(_, lifetimes, s) | LateScope(lifetimes, s) => { if let Some((_, lifetime_def)) = search_lifetimes(lifetimes, lifetime) { - self.sess.span_warn( + self.sess.span_err( lifetime.span, &format!("lifetime name `{}` shadows another \ lifetime name that is already in scope", @@ -516,10 +516,6 @@ impl<'a> LifetimeContext<'a> { lifetime_def.span, &format!("shadowed lifetime `{}` declared here", token::get_name(lifetime.name))); - self.sess.span_note( - lifetime.span, - "shadowed lifetimes are deprecated \ - and will become a hard error before 1.0"); return; } From 92d00262c36e12ed848ca8b248cb81f16e7f2deb Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 6 Apr 2015 11:14:21 +0200 Subject: [PATCH 03/10] Replace alpha state by pre-1.0 --- src/doc/trpl/hello-cargo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/hello-cargo.md b/src/doc/trpl/hello-cargo.md index b45211e3a08..ae2a79bafec 100644 --- a/src/doc/trpl/hello-cargo.md +++ b/src/doc/trpl/hello-cargo.md @@ -1,7 +1,7 @@ % Hello, Cargo! [Cargo](http://crates.io) is a tool that Rustaceans use to help manage their -Rust projects. Cargo is currently in an alpha state, just like Rust, and so it +Rust projects. Cargo is currently in a pre-1.0 state, just like Rust, and so it is still a work in progress. However, it is already good enough to use for many Rust projects, and so it is assumed that Rust projects will use Cargo from the beginning. From 49f2a566663b125334245563f4dbe51778296feb Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Mon, 6 Apr 2015 09:35:12 -0400 Subject: [PATCH 04/10] Fix tests --- src/test/compile-fail/shadowed-lifetime.rs | 11 ++--------- src/test/run-pass/overloaded-index-assoc-list.rs | 2 +- 2 files changed, 3 insertions(+), 10 deletions(-) diff --git a/src/test/compile-fail/shadowed-lifetime.rs b/src/test/compile-fail/shadowed-lifetime.rs index 725f83d4957..110b1a0d90c 100644 --- a/src/test/compile-fail/shadowed-lifetime.rs +++ b/src/test/compile-fail/shadowed-lifetime.rs @@ -15,16 +15,14 @@ struct Foo<'a>(&'a isize); impl<'a> Foo<'a> { //~^ NOTE shadowed lifetime `'a` declared here fn shadow_in_method<'a>(&'a self) -> &'a isize { - //~^ WARNING lifetime name `'a` shadows another lifetime name that is already in scope - //~| NOTE deprecated + //~^ ERROR lifetime name `'a` shadows another lifetime name that is already in scope self.0 } fn shadow_in_type<'b>(&'b self) -> &'b isize { //~^ NOTE shadowed lifetime `'b` declared here let x: for<'b> fn(&'b isize) = panic!(); - //~^ WARNING lifetime name `'b` shadows another lifetime name that is already in scope - //~| NOTE deprecated + //~^ ERROR lifetime name `'b` shadows another lifetime name that is already in scope self.0 } @@ -35,9 +33,4 @@ impl<'a> Foo<'a> { } fn main() { - // intentional error that occurs after `resolve_lifetime` runs, - // just to ensure that this test fails to compile; when shadowed - // lifetimes become either an error or a proper lint, this will - // not be needed. - let x: isize = 3_usize; //~ ERROR mismatched types } diff --git a/src/test/run-pass/overloaded-index-assoc-list.rs b/src/test/run-pass/overloaded-index-assoc-list.rs index 131098d7c94..d98b1d9deae 100644 --- a/src/test/run-pass/overloaded-index-assoc-list.rs +++ b/src/test/run-pass/overloaded-index-assoc-list.rs @@ -35,7 +35,7 @@ impl AssociationList { impl<'a, K: PartialEq + std::fmt::Debug, V:Clone> Index<&'a K> for AssociationList { type Output = V; - fn index<'a>(&'a self, index: &K) -> &'a V { + fn index(&self, index: &K) -> &V { for pair in &self.pairs { if pair.key == *index { return &pair.value From d16677282a35e92291ee048809afb6c8061ee3e5 Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Sat, 4 Apr 2015 06:30:35 -0400 Subject: [PATCH 05/10] Try to improve PhantomData docs with more examples --- src/libcore/marker.rs | 67 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 9 deletions(-) diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 619f983aee0..1953f4689ab 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -356,8 +356,49 @@ pub trait PhantomFn { } /// /// # Examples /// -/// When handling external resources over a foreign function interface, `PhantomData` can -/// prevent mismatches by enforcing types in the method implementations: +/// ## Unused lifetime parameter +/// +/// Perhaps the most common time that `PhantomData` is required is +/// with a struct that has an unused lifetime parameter, typically as +/// part of some unsafe code. For example, here is a struct `Slice` +/// that has two pointers of type `*const T`, presumably pointing into +/// an array somewhere: +/// +/// ``` +/// struct Slice<'a, T> { +/// start: *const T, +/// end: *const T, +/// } +/// ``` +/// +/// The intention is that the underlying data is only valid for the +/// lifetime `'a`, so `Slice` should not outlive `'a`. However, this +/// intent is not expressed in the code, since there are no uses of +/// the lifetime `'a` and hence it is not clear what data it applies +/// to. We can correct this by telling the compiler to act *as if* the +/// `Slice` struct contained a borrowed reference `&'a T`: +/// +/// ``` +/// use std::marker::PhantomData; +/// +/// struct Slice<'a, T:'a> { +/// start: *const T, +/// end: *const T, +/// phantom: PhantomData<&'a T> +/// } +/// ``` +/// +/// This also in turn requires that we annotate `T:'a`, indicating +/// that `T` is a type that can be borrowed for the lifetime `'a`. +/// +/// ## Unused type parameters +/// +/// It sometimes happens that there are unused type parameters that +/// indicate what type of data a struct is "tied" to, even though that +/// data is not actually found in the struct itself. Here is an +/// example where this arises when handling external resources over a +/// foreign function interface. `PhantomData` can prevent +/// mismatches by enforcing types in the method implementations: /// /// ``` /// # trait ResType { fn foo(&self); }; @@ -391,13 +432,21 @@ pub trait PhantomFn { } /// } /// ``` /// -/// Another example: embedding a `PhantomData` will inform the compiler -/// that one or more instances of the type `T` could be dropped when -/// instances of the type itself is dropped, though that may not be -/// apparent from the other structure of the type itself. This is -/// commonly necessary if the structure is using an unsafe pointer -/// like `*mut T` whose referent may be dropped when the type is -/// dropped, as a `*mut T` is otherwise not treated as owned. +/// ## Indicating ownership +/// +/// Adding a field of type `PhantomData` also indicates that your +/// struct owns data of type `T`. This in turn implies that when your +/// struct is dropped, it may in turn drop one or more instances of +/// the type `T`, though that may not be apparent from the other +/// structure of the type itself. This is commonly necessary if the +/// structure is using an unsafe pointer like `*mut T` whose referent +/// may be dropped when the type is dropped, as a `*mut T` is +/// otherwise not treated as owned. +/// +/// If your struct does not in fact *own* the data of type `T`, it is +/// better to use a reference type, like `PhantomData<&'a T>` +/// (ideally) or `PhantomData<*const T>` (if no lifetime applies), so +/// as not to indicate ownership. #[lang="phantom_data"] #[stable(feature = "rust1", since = "1.0.0")] pub struct PhantomData; From 3b9847e886d5c92b75569e49de06a6fb7490bcb4 Mon Sep 17 00:00:00 2001 From: Tobias Bucher Date: Mon, 6 Apr 2015 16:01:01 +0200 Subject: [PATCH 06/10] Fix code formatting in `core::ops::Add` example --- src/libcore/ops.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index faf305c6a13..00039c4fcdf 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -172,13 +172,13 @@ macro_rules! forward_ref_binop { /// type Output = Foo; /// /// fn add(self, _rhs: Foo) -> Foo { -/// println!("Adding!"); -/// self -/// } +/// println!("Adding!"); +/// self +/// } /// } /// /// fn main() { -/// Foo + Foo; +/// Foo + Foo; /// } /// ``` #[lang="add"] From 59d889805e7303e862d02f22aba0887ce49975e7 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Mon, 6 Apr 2015 08:14:11 -0700 Subject: [PATCH 07/10] traits.md: Fix example of using traits to match description traits.md said: If we add a `use` line right above `main` and make the right things public, everything is fine: However, the use line was actually placed at the top of the file instead. Move the use line to right above main. That also makes the example more evocative of cases where the module is defined in a separate file. --- src/doc/trpl/traits.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/doc/trpl/traits.md b/src/doc/trpl/traits.md index 341c90a7087..2986de4179b 100644 --- a/src/doc/trpl/traits.md +++ b/src/doc/trpl/traits.md @@ -229,8 +229,6 @@ everything is fine: ```{rust} # #![feature(core)] -use shapes::HasArea; - mod shapes { use std::f64::consts; @@ -251,6 +249,7 @@ mod shapes { } } +use shapes::HasArea; fn main() { let c = shapes::Circle { From 8fcc5bd6a7db63f435f7a789d3134f6e86cf693d Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Mon, 6 Apr 2015 08:36:37 -0700 Subject: [PATCH 08/10] Fix broken link and markup in `trait Any` docs. --- src/libcore/any.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/libcore/any.rs b/src/libcore/any.rs index 320fdd50b35..687675f12ef 100644 --- a/src/libcore/any.rs +++ b/src/libcore/any.rs @@ -83,11 +83,12 @@ use marker::{Reflect, Sized}; // Any trait /////////////////////////////////////////////////////////////////////////////// -/// A type to emulate dynamic typing. See the [module-level documentation][mod] for more details. +/// A type to emulate dynamic typing. /// /// Every type with no non-`'static` references implements `Any`. +/// See the [module-level documentation][mod] for more details. /// -/// [mod]: ../index.html +/// [mod]: index.html #[stable(feature = "rust1", since = "1.0.0")] pub trait Any: Reflect + 'static { /// Get the `TypeId` of `self` From 6e86c636e550cec54f51f1ce56a1f583dd37c90d Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Mon, 6 Apr 2015 08:40:11 -0700 Subject: [PATCH 09/10] Remove outdated notice from BufRead::lines docs. There is no `read_string` function, and `lines` never returns an error. --- src/libstd/io/mod.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index c6335015d72..f0f37117ed3 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -618,9 +618,6 @@ pub trait BufRead: Read { /// The iterator returned from this function will yield instances of /// `io::Result`. Each string returned will *not* have a newline /// byte (the 0xA byte) at the end. - /// - /// This function will yield errors whenever `read_string` would have also - /// yielded an error. #[stable(feature = "rust1", since = "1.0.0")] fn lines(self) -> Lines where Self: Sized { Lines { buf: self } From ae64d8e41538fc760b20185e3f2d63826bc1bd34 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Tue, 7 Apr 2015 22:10:55 +0530 Subject: [PATCH 10/10] doc ignore (fixup #24059) --- src/libcore/marker.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 9b16bd6fe84..d6a7126a883 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -324,7 +324,7 @@ impl PhantomFn for T { } /// that has two pointers of type `*const T`, presumably pointing into /// an array somewhere: /// -/// ``` +/// ```ignore /// struct Slice<'a, T> { /// start: *const T, /// end: *const T,