Auto merge of #24156 - Manishearth:rollup, r=Manishearth

Author: bors

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;
 

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.

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]

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 {

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`

src/libcore/marker.rs

@@ -316,8 +316,49 @@ impl<A:?Sized,R:?Sized,T:?Sized> PhantomFn<A,R> for T { }
 ///
 /// # Examples
 ///
-/// When handling external resources over a foreign function interface, `PhantomData<T>` 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:
+///
+/// ```ignore
+/// 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<T>` can prevent
+/// mismatches by enforcing types in the method implementations:
 ///
 /// ```
 /// # trait ResType { fn foo(&self); };
@@ -351,13 +392,21 @@ impl<A:?Sized,R:?Sized,T:?Sized> PhantomFn<A,R> for T { }
 /// }
 /// ```
 ///
-/// Another example: embedding a `PhantomData<T>` 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<T>` 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<T:?Sized>;

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"]

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;
                     }
 

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<String>`. 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<Self> where Self: Sized {
         Lines { buf: self }

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
 }

src/test/run-pass/overloaded-index-assoc-list.rs

@@ -35,7 +35,7 @@ impl<K,V> AssociationList<K,V> {
 impl<'a, K: PartialEq + std::fmt::Debug, V:Clone> Index<&'a K> for AssociationList<K,V> {
     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