Rollup of 25 pull requests

mk/clean.mk

@@ -35,7 +35,7 @@ clean-all: clean clean-llvm
 
 clean-llvm: $(CLEAN_LLVM_RULES)
 
-clean: clean-misc $(CLEAN_STAGE_RULES)
+clean: clean-misc clean-grammar $(CLEAN_STAGE_RULES)
 
 clean-misc:
 	@$(call E, cleaning)
@@ -47,6 +47,10 @@ clean-misc:
 	$(Q)rm -Rf dist/*
 	$(Q)rm -Rf doc
 
+clean-grammar:
+	@$(call E, cleaning grammar verification)
+	$(Q)cd src/grammar && rm -Rf verify *.class *.java *.tokens
+	$(Q)rm -Rf grammar
 define CLEAN_GENERIC
 
 clean-generic-$(2)-$(1):

mk/grammar.mk

@@ -37,7 +37,7 @@ $(BG):
 
 $(BG)RustLexer.class: $(BG) $(SG)RustLexer.g4
 	$(Q)$(CFG_ANTLR4) -o $(BG) $(SG)RustLexer.g4
-	$(Q)$(CFG_JAVAC) -d $(BG) $(BG)RustLexer.java
+	$(Q)$(CFG_JAVAC) -d $(BG) -classpath /usr/share/java/antlr-complete.jar $(BG)RustLexer.java
 
 check-build-lexer-verifier: $(BG)verify
 

mk/tests.mk

@@ -243,7 +243,8 @@ cleantestlibs:
 
 .PHONY: tidy
 tidy: $(HBIN0_H_$(CFG_BUILD))/tidy$(X_$(CFG_BUILD)) \
-		$(SNAPSHOT_RUSTC_POST_CLEANUP)
+		$(SNAPSHOT_RUSTC_POST_CLEANUP) \
+		check-build-lexer-verifier
 	$(TARGET_RPATH_VAR0_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $< $(S)src
 
 $(HBIN0_H_$(CFG_BUILD))/tidy$(X_$(CFG_BUILD)): \

src/doc/book/guessing-game.md

@@ -365,7 +365,7 @@ numbers. A bare number like above is actually shorthand for `^0.3.0`,
 meaning "anything compatible with 0.3.0".
 If we wanted to use only `0.3.0` exactly, we could say `rand="=0.3.0"`
 (note the two equal signs).
-And if we wanted to use the latest version we could use `*`.
+And if we wanted to use the latest version we could use `rand="*"`.
 We could also use a range of versions.
 [Cargo’s documentation][cargodoc] contains more details.
 

src/doc/book/the-stack-and-the-heap.md

@@ -26,6 +26,8 @@ The stack is very fast, and is where memory is allocated in Rust by default.
 But the allocation is local to a function call, and is limited in size. The
 heap, on the other hand, is slower, and is explicitly allocated by your
 program. But it’s effectively unlimited in size, and is globally accessible.
+Note this meaning of heap, which allocates arbitrary-sized blocks of memory in arbitrary
+order, is quite different from the heap data structure.  
 
 # The Stack
 

src/doc/rustc-ux-guidelines.md

@@ -56,6 +56,10 @@ Error explanations are long form descriptions of error messages provided with
 the compiler. They are accessible via the `--explain` flag. Each explanation
 comes with an example of how to trigger it and advice on how to fix it.
 
+Long error codes explanations are a very important part of Rust. Having an
+explanation of what failed helps to understand the error and is appreciated by
+Rust developers of all skill levels.
+
 * All of them are accessible [online](http://doc.rust-lang.org/error-index.html),
   which are auto-generated from rustc source code in different places:
   [librustc](https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs),
@@ -74,6 +78,122 @@ code with backticks.
 * When talking about the compiler, call it `the compiler`, not `Rust` or
 `rustc`.
 
+Note: The following sections are mostly a repaste of [RFC 1567](https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md).
+
+### Template
+
+Long error descriptions should match the following template. The next few
+sections of this document describe what each section is about.
+
+    E000: r##"
+    [Error description]
+
+    Example of erroneous code:
+
+    ```compile_fail
+    [Minimal example]
+    ```
+
+    [Error explanation]
+
+    ```
+    [How to fix the problem]
+    ```
+
+    [Optional Additional information]
+
+    "##,
+
+### Error description
+
+Provide a more detailed error message. For example:
+
+```ignore
+extern crate a;
+extern crate b as a;
+```
+
+We get the `E0259` error code which says "an extern crate named `a` has already been imported in this module" and the error explanation says: "The name chosen for an external crate conflicts with another external crate that has been imported into the current module.".
+
+### Minimal example
+
+Provide an erroneous code example which directly follows `Error description`. The erroneous example will be helpful for the `How to fix the problem`. Making it as simple as possible is really important in order to help readers to understand what the error is about. A comment should be added with the error on the same line where the errors occur. Example:
+
+```ignore
+type X = u32<i32>; // error: type parameters are not allowed on this type
+```
+
+If the error comments is too long to fit 80 columns, split it up like this, so the next line start at the same column of the previous line:
+
+```ignore
+type X = u32<'static>; // error: lifetime parameters are not allowed on
+                       //        this type
+```
+
+And if the sample code is too long to write an effective comment, place your comment on the line before the sample code:
+
+```ignore
+// error: lifetime parameters are not allowed on this type
+fn super_long_function_name_and_thats_problematic() {}
+```
+
+Of course, it the comment is too long, the split rules still applies.
+
+### Error explanation
+
+Provide a full explanation about "__why__ you get the error" and some leads on __how__ to fix it. If needed, use additional code snippets to improve your explanations.
+
+### How to fix the problem
+
+This part will show how to fix the error that we saw previously in the `Minimal example`, with comments explaining how it was fixed.
+
+### Additional information
+
+Some details which might be useful for the users, let's take back `E0109` example. At the end, the supplementary explanation is the following: "Note that type parameters for enum-variant constructors go after the variant, not after the enum (`Option::None::<u32>`, not `Option::<u32>::None`).". It provides more information, not directly linked to the error, but it might help user to avoid doing another error.
+
+### Full Example
+
+    E0409: r##"
+    An "or" pattern was used where the variable bindings are not consistently bound
+    across patterns.
+
+    Example of erroneous code:
+
+    ```compile_fail,E0409
+    let x = (0, 2);
+    match x {
+        (0, ref y) | (y, 0) ={ /* use y */} // error: variable `y` is bound with
+                                              //        different mode in pattern #2
+                                              //        than in pattern #1
+        _ =()
+    }
+    ```
+
+    Here, `y` is bound by-value in one case and by-reference in the other.
+
+    To fix this error, just use the same mode in both cases.
+    Generally using `ref` or `ref mut` where not already used will fix this:
+
+    ```rust
+    let x = (0, 2);
+    match x {
+        (0, ref y) | (ref y, 0) ={ /* use y */}
+        _ =()
+    }
+    ```
+
+    Alternatively, split the pattern:
+
+    ```rust
+    let x = (0, 2);
+    match x {
+        (y, 0) ={ /* use y */ }
+        (0, ref y) ={ /* use y */}
+        _ =()
+    }
+    ```
+    "##,
+
 ## Compiler Flags
 
 * Flags should be orthogonal to each other. For example, if we'd have a

src/grammar/README.md

@@ -4,11 +4,11 @@ Uses [antlr4](http://www.antlr.org/) and a custom Rust tool to compare
 ASTs/token streams generated. You can use the `check-lexer` make target to
 run all of the available tests.
 
-To use manually:
+To use manually, assuming antlr4 ist installed at `/usr/share/java/antlr-complete.jar`:
 
 ```
 antlr4 RustLexer.g4
-javac *.java
+javac -classpath /usr/share/java/antlr-complete.jar *.java
 rustc -O verify.rs
 for file in ../*/**.rs; do
     echo $file;

src/grammar/check.sh

@@ -20,11 +20,11 @@ skipped=0
 check() {
     grep --silent "// ignore-lexer-test" "$1";
 
-    # if it's *not* found...
+    # if it is *not* found...
     if [ $? -eq 1 ]; then
-        cd $2 # This `cd` is so java will pick up RustLexer.class. I couldn't
+        cd $2 # This `cd` is so java will pick up RustLexer.class. I could not
         # figure out how to wrangle the CLASSPATH, just adding build/grammar
-        # didn't seem to have any effect.
+        # did not seem to have any effect.
         if $3 RustLexer tokens -tokens < $1 | $4 $1 $5; then
             echo "pass: $1"
             passed=`expr $passed + 1`

src/grammar/verify.rs

@@ -11,6 +11,7 @@
 #![feature(plugin, rustc_private)]
 
 extern crate syntax;
+extern crate syntax_pos;
 extern crate rustc;
 
 #[macro_use]
@@ -290,9 +291,10 @@ fn main() {
 
     let options = config::basic_options();
     let session = session::build_session(options, &DepGraph::new(false), None,
-                                         syntax::diagnostics::registry::Registry::new(&[]),
+                                         syntax::errors::registry::Registry::new(&[]),
                                          Rc::new(DummyCrateStore));
-    let filemap = session.parse_sess.codemap().new_filemap(String::from("<n/a>"), code);
+    let filemap = session.parse_sess.codemap()
+                         .new_filemap("<n/a>".to_string(), None, code);
     let mut lexer = lexer::StringReader::new(session.diagnostic(), filemap);
     let cm = session.codemap();
 

src/libcollections/range.rs

@@ -23,13 +23,45 @@ pub trait RangeArgument<T> {
     /// Start index (inclusive)
     ///
     /// Return start value if present, else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(collections)]
+    /// #![feature(collections_range)]
+    ///
+    /// extern crate collections;
+    ///
+    /// # fn main() {
+    /// use collections::range::RangeArgument;
+    ///
+    /// assert_eq!((..10).start(), None);
+    /// assert_eq!((3..10).start(), Some(&3));
+    /// # }
+    /// ```
     fn start(&self) -> Option<&T> {
         None
     }
 
     /// End index (exclusive)
     ///
     /// Return end value if present, else `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(collections)]
+    /// #![feature(collections_range)]
+    ///
+    /// extern crate collections;
+    ///
+    /// # fn main() {
+    /// use collections::range::RangeArgument;
+    ///
+    /// assert_eq!((3..).end(), None);
+    /// assert_eq!((3..10).end(), Some(&10));
+    /// # }
+    /// ```
     fn end(&self) -> Option<&T> {
         None
     }

src/libcollections/vec.rs

@@ -476,6 +476,25 @@ impl<T> Vec<T> {
     /// Note that this will drop any excess capacity. Calling this and
     /// converting back to a vector with `into_vec()` is equivalent to calling
     /// `shrink_to_fit()`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let v = vec![1, 2, 3];
+    ///
+    /// let slice = v.into_boxed_slice();
+    /// ```
+    ///
+    /// Any excess capacity is removed:
+    ///
+    /// ```
+    /// let mut vec = Vec::with_capacity(10);
+    /// vec.extend([1, 2, 3].iter().cloned());
+    ///
+    /// assert_eq!(vec.capacity(), 10);
+    /// let slice = vec.into_boxed_slice();
+    /// assert_eq!(slice.into_vec().capacity(), 3);
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn into_boxed_slice(mut self) -> Box<[T]> {
         unsafe {

src/libcore/marker.rs

@@ -144,6 +144,12 @@ pub trait Unsize<T: ?Sized> {
 /// Generalizing the latter case, any type implementing `Drop` can't be `Copy`, because it's
 /// managing some resource besides its own `size_of::<T>()` bytes.
 ///
+/// ## What if I derive `Copy` on a type that can't?
+///
+/// If you try to derive `Copy` on a struct or enum, you will get a compile-time error.
+/// Specifically, with structs you'll get [E0204](https://doc.rust-lang.org/error-index.html#E0204)
+/// and with enums you'll get [E0205](https://doc.rust-lang.org/error-index.html#E0205).
+///
 /// ## When should my type be `Copy`?
 ///
 /// Generally speaking, if your type _can_ implement `Copy`, it should. There's one important thing

src/libcore/raw.rs

@@ -34,12 +34,13 @@
 /// only designed to be used by unsafe code that needs to manipulate
 /// the low-level details.
 ///
-/// There is no `Repr` implementation for `TraitObject` because there
-/// is no way to refer to all trait objects generically, so the only
+/// There is no way to refer to all trait objects generically, so the only
 /// way to create values of this type is with functions like
-/// `std::mem::transmute`. Similarly, the only way to create a true
+/// [`std::mem::transmute`][transmute]. Similarly, the only way to create a true
 /// trait object from a `TraitObject` value is with `transmute`.
 ///
+/// [transmute]: ../mem/fn.transmute.html
+///
 /// Synthesizing a trait object with mismatched types—one where the
 /// vtable does not correspond to the type of the value to which the
 /// data pointer points—is highly likely to lead to undefined
@@ -50,13 +51,13 @@
 /// ```
 /// #![feature(raw)]
 ///
-/// use std::mem;
-/// use std::raw;
+/// use std::{mem, raw};
 ///
 /// // an example trait
 /// trait Foo {
 ///     fn bar(&self) -> i32;
 /// }
+///
 /// impl Foo for i32 {
 ///     fn bar(&self) -> i32 {
 ///          *self + 1
@@ -74,19 +75,18 @@
 /// // the data pointer is the address of `value`
 /// assert_eq!(raw_object.data as *const i32, &value as *const _);
 ///
-///
 /// let other_value: i32 = 456;
 ///
 /// // construct a new object, pointing to a different `i32`, being
 /// // careful to use the `i32` vtable from `object`
 /// let synthesized: &Foo = unsafe {
 ///      mem::transmute(raw::TraitObject {
 ///          data: &other_value as *const _ as *mut (),
-///          vtable: raw_object.vtable
+///          vtable: raw_object.vtable,
 ///      })
 /// };
 ///
-/// // it should work just like we constructed a trait object out of
+/// // it should work just as if we had constructed a trait object out of
 /// // `other_value` directly
 /// assert_eq!(synthesized.bar(), 457);
 /// ```