Rollup of 6 pull requests

src/doc/book/patterns.md

@@ -23,6 +23,33 @@ match x {
 
 This prints `one`.
 
+It's possible to create a binding for the value in the any case:
+
+```rust
+let x = 1;
+
+match x {
+    y => println!("x: {} y: {}", x, y),
+}
+```
+
+This prints:
+
+```text
+x: 1 y: 1
+```
+
+Note it is an error to have both a catch-all `_` and a catch-all binding in the same match block:
+
+```rust
+let x = 1;
+
+match x {
+    y => println!("x: {} y: {}", x, y),
+    _ => println!("anything"), // this causes an error as it is unreachable
+}
+```
+
 There’s one pitfall with patterns: like anything that introduces a new binding,
 they introduce shadowing. For example:
 

src/libcollections/btree/map.rs

@@ -656,7 +656,7 @@ impl<K: Ord, V> BTreeMap<K, V> {
     }
 
     /// Constructs a double-ended iterator over a sub-range of elements in the map.
-    /// The simplest way is to use the range synax `min..max`, thus `range(min..max)` will
+    /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will
     /// yield elements from min (inclusive) to max (exclusive).
     /// The range may also be entered as `(Bound<T>, Bound<T>)`, so for example
     /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive
@@ -748,7 +748,7 @@ impl<K: Ord, V> BTreeMap<K, V> {
     }
 
     /// Constructs a mutable double-ended iterator over a sub-range of elements in the map.
-    /// The simplest way is to use the range synax `min..max`, thus `range(min..max)` will
+    /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will
     /// yield elements from min (inclusive) to max (exclusive).
     /// The range may also be entered as `(Bound<T>, Bound<T>)`, so for example
     /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive

src/libcollections/btree/set.rs

@@ -208,7 +208,7 @@ impl<T> BTreeSet<T> {
 
 impl<T: Ord> BTreeSet<T> {
     /// Constructs a double-ended iterator over a sub-range of elements in the set.
-    /// The simplest way is to use the range synax `min..max`, thus `range(min..max)` will
+    /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will
     /// yield elements from min (inclusive) to max (exclusive).
     /// The range may also be entered as `(Bound<T>, Bound<T>)`, so for example
     /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive

src/libcore/macros.rs

@@ -45,7 +45,8 @@ macro_rules! panic {
 /// Other use-cases of `assert!` include [testing] and enforcing run-time
 /// invariants in safe code (whose violation cannot result in unsafety).
 ///
-/// This macro has a second version, where a custom panic message can be provided.
+/// This macro has a second version, where a custom panic message can
+/// be provided with or without arguments for formatting.
 ///
 /// [testing]: ../book/testing.html
 ///
@@ -87,12 +88,17 @@ macro_rules! assert {
 /// On panic, this macro will print the values of the expressions with their
 /// debug representations.
 ///
+/// Like `assert!()`, this macro has a second version, where a custom
+/// panic message can be provided.
+///
 /// # Examples
 ///
 /// ```
 /// let a = 3;
 /// let b = 1 + 2;
 /// assert_eq!(a, b);
+///
+/// assert_eq!(a, b, "we are testing addition with {} and {}", a, b);
 /// ```
 #[macro_export]
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -125,12 +131,17 @@ macro_rules! assert_eq {
 /// On panic, this macro will print the values of the expressions with their
 /// debug representations.
 ///
+/// Like `assert!()`, this macro has a second version, where a custom
+/// panic message can be provided.
+///
 /// # Examples
 ///
 /// ```
 /// let a = 3;
 /// let b = 2;
 /// assert_ne!(a, b);
+///
+/// assert_ne!(a, b, "we are testing that the values are not equal");
 /// ```
 #[macro_export]
 #[stable(feature = "assert_ne", since = "1.12.0")]

src/libstd/env.rs

@@ -10,7 +10,7 @@
 
 //! Inspection and manipulation of the process's environment.
 //!
-//! This module contains methods to inspect various aspects such as
+//! This module contains functions to inspect various aspects such as
 //! environment variables, process arguments, the current directory, and various
 //! other important directories.
 
@@ -68,15 +68,17 @@ pub fn set_current_dir<P: AsRef<Path>>(p: P) -> io::Result<()> {
 
 /// An iterator over a snapshot of the environment variables of this process.
 ///
-/// This iterator is created through `std::env::vars()` and yields `(String,
-/// String)` pairs.
+/// This structure is created through the [`std::env::vars`] function.
+///
+/// [`std::env::vars`]: fn.vars.html
 #[stable(feature = "env", since = "1.0.0")]
 pub struct Vars { inner: VarsOs }
 
 /// An iterator over a snapshot of the environment variables of this process.
 ///
-/// This iterator is created through `std::env::vars_os()` and yields
-/// `(OsString, OsString)` pairs.
+/// This structure is created through the [`std::env::vars_os`] function.
+///
+/// [`std::env::vars_os`]: fn.vars_os.html
 #[stable(feature = "env", since = "1.0.0")]
 pub struct VarsOs { inner: os_imp::Env }
 
@@ -218,7 +220,9 @@ fn _var_os(key: &OsStr) -> Option<OsString> {
     })
 }
 
-/// Possible errors from the `env::var` method.
+/// Possible errors from the [`env::var`] function.
+///
+/// [env::var]: fn.var.html
 #[derive(Debug, PartialEq, Eq, Clone)]
 #[stable(feature = "env", since = "1.0.0")]
 pub enum VarError {
@@ -570,7 +574,7 @@ pub fn current_exe() -> io::Result<PathBuf> {
 /// An iterator over the arguments of a process, yielding a [`String`] value
 /// for each argument.
 ///
-/// This structure is created through the [`std::env::args`] method.
+/// This structure is created through the [`std::env::args`] function.
 ///
 /// [`String`]: ../string/struct.String.html
 /// [`std::env::args`]: ./fn.args.html
@@ -580,7 +584,7 @@ pub struct Args { inner: ArgsOs }
 /// An iterator over the arguments of a process, yielding an [`OsString`] value
 /// for each argument.
 ///
-/// This structure is created through the [`std::env::args_os`] method.
+/// This structure is created through the [`std::env::args_os`] function.
 ///
 /// [`OsString`]: ../ffi/struct.OsString.html
 /// [`std::env::args_os`]: ./fn.args_os.html

src/libstd/sys/unix/ext/ffi.rs

@@ -20,11 +20,38 @@ use sys_common::{FromInner, IntoInner, AsInner};
 /// Unix-specific extensions to `OsString`.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait OsStringExt {
-    /// Creates an `OsString` from a byte vector.
+    /// Creates an [`OsString`] from a byte vector.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::OsString;
+    /// use std::os::unix::ffi::OsStringExt;
+    ///
+    /// let bytes = b"foo".to_vec();
+    /// let os_string = OsString::from_vec(bytes);
+    /// assert_eq!(os_string.to_str(), Some("foo"));
+    /// ```
+    ///
+    /// [`OsString`]: ../../../ffi/struct.OsString.html
     #[stable(feature = "rust1", since = "1.0.0")]
     fn from_vec(vec: Vec<u8>) -> Self;
 
-    /// Yields the underlying byte vector of this `OsString`.
+    /// Yields the underlying byte vector of this [`OsString`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::OsString;
+    /// use std::os::unix::ffi::OsStringExt;
+    ///
+    /// let mut os_string = OsString::new();
+    /// os_string.push("foo");
+    /// let bytes = os_string.into_vec();
+    /// assert_eq!(bytes, b"foo");
+    /// ```
+    ///
+    /// [`OsString`]: ../../../ffi/struct.OsString.html
     #[stable(feature = "rust1", since = "1.0.0")]
     fn into_vec(self) -> Vec<u8>;
 }
@@ -43,9 +70,36 @@ impl OsStringExt for OsString {
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait OsStrExt {
     #[stable(feature = "rust1", since = "1.0.0")]
+    /// Creates an [`OsStr`] from a byte slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::OsStr;
+    /// use std::os::unix::ffi::OsStrExt;
+    ///
+    /// let bytes = b"foo";
+    /// let os_str = OsStr::from_bytes(bytes);
+    /// assert_eq!(os_str.to_str(), Some("foo"));
+    /// ```
+    ///
+    /// [`OsStr`]: ../../../ffi/struct.OsStr.html
     fn from_bytes(slice: &[u8]) -> &Self;
 
-    /// Gets the underlying byte view of the `OsStr` slice.
+    /// Gets the underlying byte view of the [`OsStr`] slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::OsStr;
+    /// use std::os::unix::ffi::OsStrExt;
+    ///
+    /// let mut os_str = OsStr::new("foo");
+    /// let bytes = os_str.as_bytes();
+    /// assert_eq!(bytes, b"foo");
+    /// ```
+    ///
+    /// [`OsStr`]: ../../../ffi/struct.OsStr.html
     #[stable(feature = "rust1", since = "1.0.0")]
     fn as_bytes(&self) -> &[u8];
 }