Auto merge of #31523 - steveklabnik:rollup, r=steveklabnik

- Successful merges: #31473, #31513, #31514, #31515, #31516, #31520
- Failed merges:

25 files changed, 165 insertions, 115 deletions

diff --git a/src/doc/book/error-handling.md b/src/doc/book/error-handling.md
index 73875704eca..11086af10bd 100644
--- a/src/doc/book/error-handling.md
+++ b/src/doc/book/error-handling.md
@@ -265,7 +265,7 @@ fn map<F, T, A>(option: Option<T>, f: F) -> Option<A> where F: FnOnce(T) -> A {
 ```
 
 Indeed, `map` is [defined as a method][2] on `Option<T>` in the standard library.
-As a method, it has a slighly different signature: methods take `self`, `&self`,
+As a method, it has a slightly different signature: methods take `self`, `&self`,
 or `&mut self` as their first argument.
 
 Armed with our new combinator, we can rewrite our `extension_explicit` method
@@ -1592,7 +1592,7 @@ fn print_usage(program: &str, opts: Options) {
 
 fn main() {
     let args: Vec<String> = env::args().collect();
-    let program = args[0].clone();
+    let program = &args[0];
 
     let mut opts = Options::new();
     opts.optflag("h", "help", "Show this usage message.");
@@ -1605,10 +1605,10 @@ fn main() {
         print_usage(&program, opts);
         return;
     }
-    let data_path = args[1].clone();
-    let city = args[2].clone();
+    let data_path = &args[1];
+    let city = &args[2];
 
-	// Do stuff with information
+    // Do stuff with information
 }
 ```
 
@@ -1640,7 +1640,6 @@ sure to add `extern crate csv;` to the top of your file.)
 
 ```rust,ignore
 use std::fs::File;
-use std::path::Path;
 
 // This struct represents the data in each row of the CSV file.
 // Type based decoding absolves us of a lot of the nitty gritty error
@@ -1666,7 +1665,7 @@ fn print_usage(program: &str, opts: Options) {
 
 fn main() {
     let args: Vec<String> = env::args().collect();
-    let program = args[0].clone();
+    let program = &args[0];
 
     let mut opts = Options::new();
     opts.optflag("h", "help", "Show this usage message.");
@@ -1678,25 +1677,24 @@ fn main() {
 
     if matches.opt_present("h") {
         print_usage(&program, opts);
-		return;
-	}
+        return;
+    }
 
-	let data_file = args[1].clone();
-	let data_path = Path::new(&data_file);
-	let city = args[2].clone();
+    let data_path = &args[1];
+    let city: &str = &args[2];
 
-	let file = File::open(data_path).unwrap();
-	let mut rdr = csv::Reader::from_reader(file);
+    let file = File::open(data_path).unwrap();
+    let mut rdr = csv::Reader::from_reader(file);
 
-	for row in rdr.decode::<Row>() {
-		let row = row.unwrap();
+    for row in rdr.decode::<Row>() {
+        let row = row.unwrap();
 
-		if row.city == city {
-			println!("{}, {}: {:?}",
-				row.city, row.country,
-				row.population.expect("population count"));
-		}
-	}
+        if row.city == city {
+            println!("{}, {}: {:?}",
+                row.city, row.country,
+                row.population.expect("population count"));
+        }
+    }
 }
 ```
 
@@ -1745,6 +1743,8 @@ Note that we opt to handle the possibility of a missing population count by
 simply ignoring that row.
 
 ```rust,ignore
+use std::path::Path;
+
 struct Row {
     // unchanged
 }
@@ -1782,27 +1782,26 @@ fn search<P: AsRef<Path>>(file_path: P, city: &str) -> Vec<PopulationCount> {
 }
 
 fn main() {
-	let args: Vec<String> = env::args().collect();
-	let program = args[0].clone();
+    let args: Vec<String> = env::args().collect();
+    let program = &args[0];
 
-	let mut opts = Options::new();
-	opts.optflag("h", "help", "Show this usage message.");
+    let mut opts = Options::new();
+    opts.optflag("h", "help", "Show this usage message.");
 
-	let matches = match opts.parse(&args[1..]) {
-		Ok(m)  => { m }
-		Err(e) => { panic!(e.to_string()) }
-	};
-	if matches.opt_present("h") {
-		print_usage(&program, opts);
-		return;
-	}
+    let matches = match opts.parse(&args[1..]) {
+        Ok(m)  => { m }
+        Err(e) => { panic!(e.to_string()) }
+    };
+    if matches.opt_present("h") {
+        print_usage(&program, opts);
+        return;
+    }
 
-	let data_file = args[1].clone();
-	let data_path = Path::new(&data_file);
-	let city = args[2].clone();
-	for pop in search(&data_path, &city) {
-		println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
-	}
+    let data_path = &args[1];
+    let city = &args[2];
+    for pop in search(data_path, city) {
+        println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
+    }
 }
 
 ```
@@ -1912,7 +1911,7 @@ First, here's the new usage:
 
 ```rust,ignore
 fn print_usage(program: &str, opts: Options) {
-	println!("{}", opts.usage(&format!("Usage: {} [options] <city>", program)));
+    println!("{}", opts.usage(&format!("Usage: {} [options] <city>", program)));
 }
 ```
 The next part is going to be only a little harder:
@@ -1924,16 +1923,16 @@ opts.optopt("f", "file", "Choose an input file, instead of using STDIN.", "NAME"
 opts.optflag("h", "help", "Show this usage message.");
 ...
 let file = matches.opt_str("f");
-let data_file = file.as_ref().map(Path::new);
+let data_file = &file.as_ref().map(Path::new);
 
 let city = if !matches.free.is_empty() {
-	matches.free[0].clone()
+    &matches.free[0]
 } else {
-	print_usage(&program, opts);
-	return;
+    print_usage(&program, opts);
+    return;
 };
 
-match search(&data_file, &city) {
+match search(data_file, city) {
     Ok(pops) => {
         for pop in pops {
             println!("{}, {}: {:?}", pop.city, pop.country, pop.count);
diff --git a/src/libbacktrace/ansidecl.h b/src/libbacktrace/ansidecl.h
index 6e4bfc21f25..4087dd72917 100644
--- a/src/libbacktrace/ansidecl.h
+++ b/src/libbacktrace/ansidecl.h
@@ -1,4 +1,4 @@
-/* ANSI and traditional C compatability macros
+/* ANSI and traditional C compatibility macros
    Copyright (C) 1991-2015 Free Software Foundation, Inc.
    This file is part of the GNU C Library.
 
diff --git a/src/libcollections/btree/node.rs b/src/libcollections/btree/node.rs
index f07962811fd..8ae23a646e4 100644
--- a/src/libcollections/btree/node.rs
+++ b/src/libcollections/btree/node.rs
@@ -28,7 +28,7 @@
 // }
 // ```
 //
-// Since Rust doesn't acutally have dependent types and polymorphic recursion,
+// Since Rust doesn't actually have dependent types and polymorphic recursion,
 // we make do with lots of unsafety.
 
 use alloc::heap;
diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs
index 20a7c651350..89b5e5b3075 100644
--- a/src/libcollections/str.rs
+++ b/src/libcollections/str.rs
@@ -1808,7 +1808,7 @@ impl str {
                 // Σ maps to σ, except at the end of a word where it maps to ς.
                 // This is the only conditional (contextual) but language-independent mapping
                 // in `SpecialCasing.txt`,
-                // so hard-code it rather than have a generic "condition" mechanim.
+                // so hard-code it rather than have a generic "condition" mechanism.
                 // See https://github.com/rust-lang/rust/issues/26035
                 map_uppercase_sigma(self, i, &mut s)
             } else {
diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs
index 7f6def68320..62ae7938e15 100644
--- a/src/libcollections/string.rs
+++ b/src/libcollections/string.rs
@@ -193,7 +193,7 @@ use boxed::Box;
 /// mem::forget(story);
 ///
 /// // We can re-build a String out of ptr, len, and capacity. This is all
-/// // unsafe becuase we are responsible for making sure the components are
+/// // unsafe because we are responsible for making sure the components are
 /// // valid:
 /// let s = unsafe { String::from_raw_parts(ptr as *mut _, len, capacity) } ;
 ///
@@ -1842,6 +1842,12 @@ impl fmt::Write for String {
 }
 
 /// A draining iterator for `String`.
+///
+/// This struct is created by the [`drain()`] method on [`String`]. See its
+/// documentation for more.
+///
+/// [`drain()`]: struct.String.html#method.drain
+/// [`String`]: struct.String.html
 #[stable(feature = "drain", since = "1.6.0")]
 pub struct Drain<'a> {
     /// Will be used as &'a mut String in the destructor
diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs
index c207ad16595..b4ac020795c 100644
--- a/src/libcore/convert.rs
+++ b/src/libcore/convert.rs
@@ -19,7 +19,7 @@
 //!
 //! - Impl the `As*` traits for reference-to-reference conversions
 //! - Impl the `Into` trait when you want to consume the value in the conversion
-//! - The `From` trait is the most flexible, usefull for values _and_ references conversions
+//! - The `From` trait is the most flexible, useful for values _and_ references conversions
 //!
 //! As a library writer, you should prefer implementing `From<T>` rather than
 //! `Into<U>`, as `From` provides greater flexibility and offer the equivalent `Into`
diff --git a/src/libcore/num/dec2flt/mod.rs b/src/libcore/num/dec2flt/mod.rs
index c0690c24bbb..9e946dc65c2 100644
--- a/src/libcore/num/dec2flt/mod.rs
+++ b/src/libcore/num/dec2flt/mod.rs
@@ -149,6 +149,13 @@ from_str_float_impl!(f32);
 from_str_float_impl!(f64);
 
 /// An error which can be returned when parsing a float.
+///
+/// This error is used as the error type for the [`FromStr`] implementation
+/// for [`f32`] and [`f64`].
+///
+/// [`FromStr`]: ../str/trait.FromStr.html
+/// [`f32`]: ../primitive.f32.html
+/// [`f64`]: ../primitive.f64.html
 #[derive(Debug, Clone, PartialEq)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct ParseFloatError {
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 99a74cf09f5..9a9dfaa2679 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -2160,7 +2160,13 @@ impl usize {
         intrinsics::mul_with_overflow }
 }
 
-/// Used for representing the classification of floating point numbers
+/// A classification of floating point numbers.
+///
+/// This `enum` is used as the return type for [`f32::classify()`] and [`f64::classify()`]. See
+/// their documentation for more.
+///
+/// [`f32::classify()`]: ../primitive.f32.html#method.classify
+/// [`f64::classify()`]: ../primitive.f64.html#method.classify
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub enum FpCategory {
@@ -2387,6 +2393,11 @@ fn from_str_radix<T: FromStrRadixHelper>(src: &str, radix: u32)
 }
 
 /// An error which can be returned when parsing an integer.
+///
+/// This error is used as the error type for the `from_str_radix()` functions
+/// on the primitive integer types, such as [`i8::from_str_radix()`].
+///
+/// [`i8::from_str_radix()`]: ../std/primitive.i8.html#method.from_str_radix
 #[derive(Debug, Clone, PartialEq)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct ParseIntError { kind: IntErrorKind }
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index f19970546d7..fa169416a10 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -1740,7 +1740,7 @@ impl StrExt for str {
         let mut matcher = pat.into_searcher(self);
         if let Some((a, b)) = matcher.next_reject() {
             i = a;
-            j = b; // Rember earliest known match, correct it below if
+            j = b; // Remember earliest known match, correct it below if
                    // last match is different
         }
         if let Some((_, b)) = matcher.next_reject_back() {
diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs
index 4127e182e1d..abaabfd129b 100644
--- a/src/libcore/tuple.rs
+++ b/src/libcore/tuple.rs
@@ -8,24 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! A finite heterogeneous sequence, `(T, U, ..)`
-//!
-//! To access a single element of a tuple one can use the `.0`
-//! field access syntax.
-//!
-//! Indexing starts from zero, so `.0` returns first value, `.1`
-//! returns second value, and so on. In general, a tuple with *N*
-//! elements has field accessors from 0 to *N* - 1.
-//!
-//! If every type inside a tuple implements one of the following
-//! traits, then a tuple itself also implements it.
-//!
-//! * `Clone`
-//! * `PartialEq`
-//! * `Eq`
-//! * `PartialOrd`
-//! * `Ord`
-//! * `Default`
+// See src/libstd/primitive_docs.rs for documentation.
 
 use clone::Clone;
 use cmp::*;
diff --git a/src/librbml/lib.rs b/src/librbml/lib.rs
index 8404026df14..1727fa2a0d3 100644
--- a/src/librbml/lib.rs
+++ b/src/librbml/lib.rs
@@ -107,7 +107,7 @@
 //!
 //! - `Opaque` (`17`): An opaque, custom-format tag.
 //!   Used to wrap ordinary custom tags or data in the auto-serialized context.
-//!   Rustc typically uses this to encode type informations.
+//!   Rustc typically uses this to encode type information.
 //!
 //! First 0x20 tags are reserved by RBML; custom tags start at 0x20.
 
diff --git a/src/librustc/middle/pat_util.rs b/src/librustc/middle/pat_util.rs
index 41367b9361f..8181e7d798c 100644
--- a/src/librustc/middle/pat_util.rs
+++ b/src/librustc/middle/pat_util.rs
@@ -153,7 +153,7 @@ pub fn pat_contains_bindings(dm: &DefMap, pat: &hir::Pat) -> bool {
 }
 
 /// Checks if the pattern contains any `ref` or `ref mut` bindings,
-/// and if yes wether its containing mutable ones or just immutables ones.
+/// and if yes whether its containing mutable ones or just immutables ones.
 pub fn pat_contains_ref_binding(dm: &RefCell<DefMap>, pat: &hir::Pat) -> Option<hir::Mutability> {
     let mut result = None;
     pat_bindings(dm, pat, |mode, _, _, _| {
@@ -172,7 +172,7 @@ pub fn pat_contains_ref_binding(dm: &RefCell<DefMap>, pat: &hir::Pat) -> Option<
 }
 
 /// Checks if the patterns for this arm contain any `ref` or `ref mut`
-/// bindings, and if yes wether its containing mutable ones or just immutables ones.
+/// bindings, and if yes whether its containing mutable ones or just immutables ones.
 pub fn arm_contains_ref_binding(dm: &RefCell<DefMap>, arm: &hir::Arm) -> Option<hir::Mutability> {
     arm.pats.iter()
             .filter_map(|pat| pat_contains_ref_binding(dm, pat))
diff --git a/src/librustc/middle/ty/mod.rs b/src/librustc/middle/ty/mod.rs
index 3a57474c303..e3357aabd5d 100644
--- a/src/librustc/middle/ty/mod.rs
+++ b/src/librustc/middle/ty/mod.rs
@@ -2236,7 +2236,7 @@ impl<'tcx> ctxt<'tcx> {
     /// Given the did of an ADT, return a reference to its definition.
     pub fn lookup_adt_def(&self, did: DefId) -> AdtDef<'tcx> {
         // when reverse-variance goes away, a transmute::<AdtDefMaster,AdtDef>
-        // woud be needed here.
+        // would be needed here.
         self.lookup_adt_def_master(did)
     }
 
diff --git a/src/librustc/mir/visit.rs b/src/librustc/mir/visit.rs
index fb4e0e97054..5e3c6e028a3 100644
--- a/src/librustc/mir/visit.rs
+++ b/src/librustc/mir/visit.rs
@@ -92,7 +92,7 @@ macro_rules! make_mir_visitor {
             }
 
             // The `super_xxx` methods comprise the default behavior and are
-            // not meant to be overidden.
+            // not meant to be overridden.
 
             fn super_mir(&mut self,
                          mir: & $($mutability)* Mir<'tcx>) {
diff --git a/src/librustc_trans/trans/common.rs b/src/librustc_trans/trans/common.rs
index ec33046e5d9..1269c266c7c 100644
--- a/src/librustc_trans/trans/common.rs
+++ b/src/librustc_trans/trans/common.rs
@@ -541,7 +541,7 @@ impl<'a, 'tcx> FunctionContext<'a, 'tcx> {
     }
 
     // Returns a ValueRef of the "eh_unwind_resume" lang item if one is defined,
-    // otherwise declares it as an external funtion.
+    // otherwise declares it as an external function.
     pub fn eh_unwind_resume(&self) -> ValueRef {
         use trans::attributes;
         assert!(self.ccx.sess().target.target.options.custom_unwind_resume);
diff --git a/src/librustc_typeck/check/mod.rs b/src/librustc_typeck/check/mod.rs
index 9a0d6bc1641..a476f9e1a80 100644
--- a/src/librustc_typeck/check/mod.rs
+++ b/src/librustc_typeck/check/mod.rs
@@ -1809,7 +1809,7 @@ impl<'a, 'tcx> FnCtxt<'a, 'tcx> {
             debug!("select_all_obligations_and_apply_defaults: defaults={:?}", default_map);
 
             // We loop over the unsolved variables, resolving them and if they are
-            // and unconstrainted numberic type we add them to the set of unbound
+            // and unconstrainted numeric type we add them to the set of unbound
             // variables. We do this so we only apply literal fallback to type
             // variables without defaults.
             for ty in &unsolved_variables {
diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 2087148d844..d42b9489180 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -521,7 +521,7 @@ impl OpenOptions {
     /// No file is allowed to exist at the target location, also no (dangling)
     /// symlink.
     ///
-    /// This option is usefull because it as atomic. Otherwise between checking
+    /// This option is useful because it as atomic. Otherwise between checking
     /// whether a file exists and creating a new one, the file may have been
     /// created by another process (a TOCTOU race condition / attack).
     ///
diff --git a/src/libstd/memchr.rs b/src/libstd/memchr.rs
index 27702e2e59a..1d97611eabb 100644
--- a/src/libstd/memchr.rs
+++ b/src/libstd/memchr.rs
@@ -150,7 +150,7 @@ mod fallback {
         // Scan for a single byte value by reading two `usize` words at a time.
         //
         // Split `text` in three parts
-        // - unaligned inital part, before the first word aligned address in text
+        // - unaligned initial part, before the first word aligned address in text
         // - body, scan by 2 words at a time
         // - the last remaining part, < 2 word size
         let len = text.len();
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index faaff494cab..dd0d874ee4b 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -8,10 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Numeric traits and functions for generic mathematics
+//! Additional functionality for numerics.
 //!
-//! These are implemented for the primitive numeric types in `std::{u8, u16,
-//! u32, u64, usize, i8, i16, i32, i64, isize, f32, f64}`.
+//! This module provides some extra types that are useful when doing numerical
+//! work. See the individual documentation for each piece for more information.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 #![allow(missing_docs)]
diff --git a/src/libstd/panic.rs b/src/libstd/panic.rs
index 3677bd27b16..83df54f1830 100644
--- a/src/libstd/panic.rs
+++ b/src/libstd/panic.rs
@@ -84,7 +84,7 @@ pub use panicking::{take_handler, set_handler, PanicInfo, Location};
 /// recover safe. The general idea is that any mutable state which can be shared
 /// across `recover` is not recover safe by default. This is because it is very
 /// easy to witness a broken invariant outside of `recover` as the data is
-/// simply accesed as usual.
+/// simply accessed as usual.
 ///
 /// Types like `&Mutex<T>`, however, are recover safe because they implement
 /// poisoning by default. They still allow witnessing a broken invariant, but
diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs
index e04a676b812..a0db471dece 100644
--- a/src/libstd/prelude/mod.rs
+++ b/src/libstd/prelude/mod.rs
@@ -17,7 +17,7 @@
 //!
 //! The *prelude* is the list of things that Rust automatically imports into
 //! every Rust program. It's kept as small as possible, and is focused on
-//! things, particuarly traits, which are used in almost every single Rust
+//! things, particularly traits, which are used in almost every single Rust
 //! program.
 //!
 //! On a technical level, Rust inserts
diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs
index ed59c51b0f0..ad93fe0094a 100644
--- a/src/libstd/primitive_docs.rs
+++ b/src/libstd/primitive_docs.rs
@@ -357,50 +357,94 @@ mod prim_str { }
 //
 /// A finite heterogeneous sequence, `(T, U, ..)`.
 ///
-/// To access the _N_-th element of a tuple one can use `N` itself
-/// as a field of the tuple.
+/// Let's cover each of those in turn:
 ///
-/// Indexing starts from zero, so `0` returns first value, `1`
-/// returns second value, and so on. In general, a tuple with _S_
-/// elements provides aforementioned fields from `0` to `S-1`.
+/// Tuples are *finite*. In other words, a tuple has a length. Here's a tuple
+/// of length `3`:
+///
+/// ```
+/// ("hello", 5, 'c');
+/// ```
+///
+/// 'Length' is also sometimes called 'arity' here; each tuple of a different
+/// length is a different, distinct type.
+///
+/// Tuples are *heterogeneous*. This means that each element of the tuple can
+/// have a different type. In that tuple above, it has the type:
+///
+/// ```rust,ignore
+/// (&'static str, i32, char)
+/// ```
+///
+/// Tuples are a *sequence*. This means that they can be accessed by position;
+/// this is called 'tuple indexing', and it looks like this:
+///
+/// ```rust
+/// let tuple = ("hello", 5, 'c');
+///
+/// assert_eq!(tuple.0, "hello");
+/// assert_eq!(tuple.1, 5);
+/// assert_eq!(tuple.2, 'c');
+/// ```
+///
+/// For more about tuples, see [the book](../../book/primitive-types.html#tuples).
+///
+/// # Trait implementations
 ///
 /// If every type inside a tuple implements one of the following
 /// traits, then a tuple itself also implements it.
 ///
-/// * `Clone`
-/// * `PartialEq`
-/// * `Eq`
-/// * `PartialOrd`
-/// * `Ord`
-/// * `Debug`
-/// * `Default`
-/// * `Hash`
+/// * [`Clone`]
+/// * [`PartialEq`]
+/// * [`Eq`]
+/// * [`PartialOrd`]
+/// * [`Ord`]
+/// * [`Debug`]
+/// * [`Default`]
+/// * [`Hash`]
+///
+/// [`Clone`]: ../clone/trait.Clone.html
+/// [`PartialEq`]: ../cmp/trait.PartialEq.html
+/// [`Eq`]: ../cmp/trait.Eq.html
+/// [`PartialOrd`]: ../cmp/trait.PartialOrd.html
+/// [`Ord`]: ../cmp/trait.Ord.html
+/// [`Debug`]: ../fmt/trait.Debug.html
+/// [`Default`]: ../default/trait.Default.html
+/// [`Hash`]: ../hash/trait.Hash.html
+///
+/// Due to a temporary restriction in Rust's type system, these traits are only
+/// implemented on tuples of arity 32 or less. In the future, this may change.
 ///
 /// # Examples
 ///
-/// Accessing elements of a tuple at specified indices:
+/// Basic usage:
 ///
 /// ```
-/// let x = ("colorless",  "green", "ideas", "sleep", "furiously");
-/// assert_eq!(x.3, "sleep");
+/// let tuple = ("hello", 5, 'c');
 ///
-/// let v = (3, 3);
-/// let u = (1, -5);
-/// assert_eq!(v.0 * u.0 + v.1 * u.1, -12);
+/// assert_eq!(tuple.0, "hello");
 /// ```
 ///
-/// Using traits implemented for tuples:
+/// Tuples are often used as a return type when you want to return more than
+/// one value:
 ///
 /// ```
-/// let a = (1, 2);
-/// let b = (3, 4);
-/// assert!(a != b);
+/// fn calculate_point() -> (i32, i32) {
+///     // Don't do a calculation, that's not the point of the example
+///     (4, 5)
+/// }
+///
+/// let point = calculate_point();
+///
+/// assert_eq!(point.0, 4);
+/// assert_eq!(point.1, 5);
+///
+/// // Combining this with patterns can be nicer.
 ///
-/// let c = b.clone();
-/// assert!(b == c);
+/// let (x, y) = calculate_point();
 ///
-/// let d : (u32, f32) = Default::default();
-/// assert_eq!(d, (0, 0.0f32));
+/// assert_eq!(x, 4);
+/// assert_eq!(y, 5);
 /// ```
 ///
 mod prim_tuple { }
diff --git a/src/test/compile-fail/issue-30438-c.rs b/src/test/compile-fail/issue-30438-c.rs
index 06d391af559..2b4d0dc339b 100644
--- a/src/test/compile-fail/issue-30438-c.rs
+++ b/src/test/compile-fail/issue-30438-c.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// Simplfied regression test for #30438, inspired by arielb1.
+// Simplified regression test for #30438, inspired by arielb1.
 
 trait Trait { type Out; }
 
diff --git a/src/test/compile-fail/traits-inductive-overflow-supertrait-oibit.rs b/src/test/compile-fail/traits-inductive-overflow-supertrait-oibit.rs
index 1362f8ac0ae..ec8db996600 100644
--- a/src/test/compile-fail/traits-inductive-overflow-supertrait-oibit.rs
+++ b/src/test/compile-fail/traits-inductive-overflow-supertrait-oibit.rs
@@ -9,7 +9,7 @@
 // except according to those terms.
 
 // OIBIT-based version of #29859, supertrait version. Test that using
-// a simple OIBIT `..` impl alone still doesn't allow arbitary bounds
+// a simple OIBIT `..` impl alone still doesn't allow arbitrary bounds
 // to be synthesized.
 
 #![feature(optin_builtin_traits)]
diff --git a/src/test/run-pass/mir_trans_calls.rs b/src/test/run-pass/mir_trans_calls.rs
index 8fdedb6581f..fc45fbf7278 100644
--- a/src/test/run-pass/mir_trans_calls.rs
+++ b/src/test/run-pass/mir_trans_calls.rs
@@ -113,7 +113,7 @@ fn test_fn_object(f: &Fn(i32, i32) -> i32, x: i32, y: i32) -> i32 {
 fn test_fn_impl(f: &&Fn(i32, i32) -> i32, x: i32, y: i32) -> i32 {
     // This call goes through the Fn implementation for &Fn provided in
     // core::ops::impls. It expands to a static Fn::call() that calls the
-    // Fn::call() implemenation of the object shim underneath.
+    // Fn::call() implementation of the object shim underneath.
     f(x, y)
 }