From ff5ba731a0f19df98e8211772f41ad3c3216089f Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 8 Dec 2016 14:54:04 -0600 Subject: [PATCH 1/6] Document the optional extra arguments to assert_eq!() / assert_ne!() And clarify that those arguments in assert!() are in fact formattable. --- src/libcore/macros.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index ba52edb1ae83..bc5392f6b884 100644 --- a/src/libcore/macros.rs +++ b/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")] From 58a470e344c877abf0baab16fc8392b9545e2ef4 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Thu, 12 Jan 2017 23:10:38 -0500 Subject: [PATCH 2/6] Minor improvements to docs in std::env structures/functions. * Call functions "functions" instead of "methods". * Link structures to their constructor functions * Add other misc. documentation links --- src/libstd/env.rs | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/src/libstd/env.rs b/src/libstd/env.rs index d843d97420a1..ae83312ec949 100644 --- a/src/libstd/env.rs +++ b/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: 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 { }) } -/// 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 { /// 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 From de73e52f5701e754a4e9a5b2c2377d2b4ba834eb Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sat, 14 Jan 2017 12:40:40 -0500 Subject: [PATCH 3/6] Add doc examples & description in `std::os::unix::ffi`. --- src/libstd/sys/unix/ext/ffi.rs | 60 ++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 3 deletions(-) diff --git a/src/libstd/sys/unix/ext/ffi.rs b/src/libstd/sys/unix/ext/ffi.rs index d59b4fc0b70b..fb9984ccbdda 100644 --- a/src/libstd/sys/unix/ext/ffi.rs +++ b/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) -> 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; } @@ -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]; } From 0dad9dcf9ec7284283ef97dd0f192060a70cfad5 Mon Sep 17 00:00:00 2001 From: Bjorn Tipling Date: Sun, 15 Jan 2017 12:27:41 -0800 Subject: [PATCH 4/6] An update to patterns documentation As it is written it creates a lot of confusion. --- src/doc/book/patterns.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/doc/book/patterns.md b/src/doc/book/patterns.md index b50fa01b8e2b..24f71608a5bf 100644 --- a/src/doc/book/patterns.md +++ b/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: From b50fb240be6c988d888667019f6308c3ef91615f Mon Sep 17 00:00:00 2001 From: Ivan Stankovic Date: Mon, 16 Jan 2017 21:24:18 +0100 Subject: [PATCH 5/6] libcollections: btree/map: fix typos --- src/libcollections/btree/map.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 782a5e31d2de..4755f8a4c55a 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -656,7 +656,7 @@ impl BTreeMap { } /// 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, Bound)`, so for example /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive @@ -748,7 +748,7 @@ impl BTreeMap { } /// 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, Bound)`, so for example /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive From 2ac4fe12f3f232cd3ca8b33eb3f14bed4ca8510b Mon Sep 17 00:00:00 2001 From: Ivan Stankovic Date: Mon, 16 Jan 2017 21:26:43 +0100 Subject: [PATCH 6/6] libcollections: btree/set: fix a typo --- src/libcollections/btree/set.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index f472b593b67a..f006ba953716 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -208,7 +208,7 @@ impl BTreeSet { impl BTreeSet { /// 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, Bound)`, so for example /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive