From 1c6048d0f4b4ad49f608f3ecba7183201d4c0eda Mon Sep 17 00:00:00 2001 From: Ulrik Sverdrup Date: Wed, 23 Nov 2016 11:33:08 +0100 Subject: [PATCH 01/10] core: Iterator docs, collect is not an adaptor --- src/libcore/iter/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs index cd2e0cb11d3..4b93bb73139 100644 --- a/src/libcore/iter/mod.rs +++ b/src/libcore/iter/mod.rs @@ -225,12 +225,12 @@ //! often called 'iterator adapters', as they're a form of the 'adapter //! pattern'. //! -//! Common iterator adapters include [`map()`], [`take()`], and [`collect()`]. +//! Common iterator adapters include [`map()`], [`take()`], and [`filter()`]. //! For more, see their documentation. //! //! [`map()`]: trait.Iterator.html#method.map //! [`take()`]: trait.Iterator.html#method.take -//! [`collect()`]: trait.Iterator.html#method.collect +//! [`filter()`]: trait.Iterator.html#method.filter //! //! # Laziness //! @@ -268,7 +268,7 @@ //! [`map()`]: trait.Iterator.html#method.map //! //! The two most common ways to evaluate an iterator are to use a `for` loop -//! like this, or using the [`collect()`] adapter to produce a new collection. +//! like this, or using the [`collect()`] method to produce a new collection. //! //! [`collect()`]: trait.Iterator.html#method.collect //! From 557369ed2eadc3861ce32c53ef0c207bc112abc0 Mon Sep 17 00:00:00 2001 From: Ulrik Sverdrup Date: Wed, 23 Nov 2016 11:33:39 +0100 Subject: [PATCH 02/10] core: Fix example for .map() Make the example use DoubleEndedIterator for map, like it said it would. --- src/libcore/iter/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs index 4b93bb73139..11f1cf5591d 100644 --- a/src/libcore/iter/mod.rs +++ b/src/libcore/iter/mod.rs @@ -920,7 +920,7 @@ unsafe impl TrustedLen for Zip /// you can also [`map()`] backwards: /// /// ```rust -/// let v: Vec = vec![1, 2, 3].into_iter().rev().map(|x| x + 1).collect(); +/// let v: Vec = vec![1, 2, 3].into_iter().map(|x| x + 1).rev().collect(); /// /// assert_eq!(v, [4, 3, 2]); /// ``` From 559141c8279429e90a8b524301c7485d70ecfb4c Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 23 Nov 2016 17:14:41 +0100 Subject: [PATCH 03/10] Add missing examples to SocketAddrV6 --- src/libstd/net/addr.rs | 84 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 1c016015b79..0aac95ac02e 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -236,6 +236,14 @@ impl SocketAddrV4 { impl SocketAddrV6 { /// Creates a new socket address from the ip/port/flowinfo/scope_id /// components. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new(ip: Ipv6Addr, port: u16, flowinfo: u32, scope_id: u32) -> SocketAddrV6 { @@ -252,6 +260,15 @@ impl SocketAddrV6 { } /// Returns the IP address associated with this socket address. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); + /// assert_eq!(socket.ip(), &Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn ip(&self) -> &Ipv6Addr { unsafe { @@ -260,18 +277,47 @@ impl SocketAddrV6 { } /// Change the IP address associated with this socket address. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); + /// socket.set_ip(Ipv6Addr::new(76, 45, 0, 0, 0, 0, 0, 0)); + /// assert_eq!(socket.ip(), &Ipv6Addr::new(76, 45, 0, 0, 0, 0, 0, 0)); + /// ``` #[stable(feature = "sockaddr_setters", since = "1.9.0")] pub fn set_ip(&mut self, new_ip: Ipv6Addr) { self.inner.sin6_addr = *new_ip.as_inner() } /// Returns the port number associated with this socket address. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); + /// assert_eq!(socket.port(), 8080); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn port(&self) -> u16 { ntoh(self.inner.sin6_port) } /// Change the port number associated with this socket address. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); + /// socket.set_port(4242); + /// assert_eq!(socket.port(), 4242); + /// ``` #[stable(feature = "sockaddr_setters", since = "1.9.0")] pub fn set_port(&mut self, new_port: u16) { self.inner.sin6_port = hton(new_port); @@ -279,12 +325,31 @@ impl SocketAddrV6 { /// Returns the flow information associated with this address, /// corresponding to the `sin6_flowinfo` field in C. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 10, 0); + /// assert_eq!(socket.flowinfo(), 10); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn flowinfo(&self) -> u32 { self.inner.sin6_flowinfo } /// Change the flow information associated with this socket address. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 10, 0); + /// socket.set_flowinfo(56); + /// assert_eq!(socket.flowinfo(), 56); + /// ``` #[stable(feature = "sockaddr_setters", since = "1.9.0")] pub fn set_flowinfo(&mut self, new_flowinfo: u32) { self.inner.sin6_flowinfo = new_flowinfo; @@ -292,12 +357,31 @@ impl SocketAddrV6 { /// Returns the scope ID associated with this address, /// corresponding to the `sin6_scope_id` field in C. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 78); + /// assert_eq!(socket.scope_id(), 78); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn scope_id(&self) -> u32 { self.inner.sin6_scope_id } /// Change the scope ID associated with this socket address. + /// + /// # Examples + /// + /// ``` + /// use std::net::{SocketAddrV6, Ipv6Addr}; + /// + /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 78); + /// socket.set_scope_id(42); + /// assert_eq!(socket.scope_id(), 42); + /// ``` #[stable(feature = "sockaddr_setters", since = "1.9.0")] pub fn set_scope_id(&mut self, new_scope_id: u32) { self.inner.sin6_scope_id = new_scope_id; From 8560991cb04050d068157b100c80c5e864ec5db9 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Wed, 23 Nov 2016 10:55:44 -0800 Subject: [PATCH 04/10] Add a tracking issue for enum_set --- src/libcollections/enum_set.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcollections/enum_set.rs b/src/libcollections/enum_set.rs index 2d12b4ccffe..79e0021b148 100644 --- a/src/libcollections/enum_set.rs +++ b/src/libcollections/enum_set.rs @@ -16,7 +16,7 @@ #![unstable(feature = "enumset", reason = "matches collection reform specification, \ waiting for dust to settle", - issue = "0")] + issue = "37966")] use core::marker; use core::fmt; From a3e03e42e1298b49b647c8f80050421458414385 Mon Sep 17 00:00:00 2001 From: fkjogu Date: Thu, 24 Nov 2016 09:49:30 +0100 Subject: [PATCH 05/10] Define `bound` argument in std::sync::mpsc::sync_channel The `bound` argument in `std::sync::mpsc::sync:channel(bound: usize)` was not defined in the documentation. --- src/libstd/sync/mpsc/mod.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 2773629c7d7..ca6e46eb15a 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -491,11 +491,11 @@ pub fn channel() -> (Sender, Receiver) { /// becomes available. These channels differ greatly in the semantics of the /// sender from asynchronous channels, however. /// -/// This channel has an internal buffer on which messages will be queued. When -/// the internal buffer becomes full, future sends will *block* waiting for the -/// buffer to open up. Note that a buffer size of 0 is valid, in which case this -/// becomes "rendezvous channel" where each send will not return until a recv -/// is paired with it. +/// This channel has an internal buffer on which messages will be queued. `bound` +/// specifies the buffer size. When the internal buffer becomes full, future sends +/// will *block* waiting for the buffer to open up. Note that a buffer size of 0 +/// is valid, in which case this becomes "rendezvous channel" where each send will +/// not return until a recv is paired with it. /// /// As with asynchronous channels, all senders will panic in `send` if the /// `Receiver` has been destroyed. From e1269ff68804e4ce16102cf60817f7219f6891b1 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Thu, 24 Nov 2016 16:26:21 -0500 Subject: [PATCH 06/10] Remove completed FIXME. https://github.com/rust-lang/rust/issues/30530 --- src/libstd/panicking.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/panicking.rs b/src/libstd/panicking.rs index 1f5b3437b61..04050a5edc4 100644 --- a/src/libstd/panicking.rs +++ b/src/libstd/panicking.rs @@ -153,7 +153,7 @@ pub fn take_hook() -> Box { match hook { Hook::Default => Box::new(default_hook), - Hook::Custom(ptr) => {Box::from_raw(ptr)} // FIXME #30530 + Hook::Custom(ptr) => Box::from_raw(ptr), } } } From a3ce39898c6d534dd75fb617f985fc7bc8c8fb29 Mon Sep 17 00:00:00 2001 From: Vickenty Fesunov Date: Fri, 25 Nov 2016 17:59:04 +0100 Subject: [PATCH 07/10] Follow our own recommendations in the examples Remove exclamation marks from the the example error descriptions: > The description [...] should not contain newlines or sentence-ending punctuation --- src/libstd/error.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 454fa47cfbc..e115263d2eb 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -109,7 +109,7 @@ pub trait Error: Debug + Display { /// /// impl Error for SuperError { /// fn description(&self) -> &str { - /// "I'm the superhero of errors!" + /// "I'm the superhero of errors" /// } /// /// fn cause(&self) -> Option<&Error> { @@ -128,7 +128,7 @@ pub trait Error: Debug + Display { /// /// impl Error for SuperErrorSideKick { /// fn description(&self) -> &str { - /// "I'm SuperError side kick!" + /// "I'm SuperError side kick" /// } /// } /// From 276d91d8cb9627eb9e748f1adb5c8c5f79ed4ae3 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Fri, 25 Nov 2016 17:43:06 -0500 Subject: [PATCH 08/10] Document how the `RwLockReadGuard` structure is created. --- src/libstd/sync/rwlock.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index f08b7641521..729ada48b44 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -77,6 +77,13 @@ unsafe impl Sync for RwLock {} /// RAII structure used to release the shared read access of a lock when /// dropped. +/// +/// This structure is created by the [`read()`] and [`try_read()`] methods on +/// [`RwLock`]. +/// +/// [`read()`]: struct.RwLock.html#method.read +/// [`try_read()`]: struct.RwLock.html#method.try_read +/// [`RwLock`]: struct.RwLock.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] pub struct RwLockReadGuard<'a, T: ?Sized + 'a> { From 6b4de8bf91f5cb21be3637de96b9fdd5a518f411 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Fri, 25 Nov 2016 17:46:12 -0500 Subject: [PATCH 09/10] Document how the `RwLockWriteGuard` structure is created. --- src/libstd/sync/rwlock.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index 729ada48b44..f83cf7ba9c2 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -95,6 +95,13 @@ impl<'a, T: ?Sized> !marker::Send for RwLockReadGuard<'a, T> {} /// RAII structure used to release the exclusive write access of a lock when /// dropped. +/// +/// This structure is created by the [`write()`] and [`try_write()`] methods +/// on [`RwLock`]. +/// +/// [`write()`]: struct.RwLock.html#method.write +/// [`try_write()`]: struct.RwLock.html#method.try_write +/// [`RwLock`]: struct.RwLock.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> { From 6075af4ac0b031f738da624ee0e9962f25f57e4c Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Fri, 25 Nov 2016 17:48:45 -0500 Subject: [PATCH 10/10] Document how the `MutexGuard` structure is created. Also, end sentence with a period. --- src/libstd/sync/mutex.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 812724c7a16..df4a3746a49 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -133,7 +133,14 @@ unsafe impl Sync for Mutex { } /// dropped (falls out of scope), the lock will be unlocked. /// /// The data protected by the mutex can be access through this guard via its -/// `Deref` and `DerefMut` implementations +/// `Deref` and `DerefMut` implementations. +/// +/// This structure is created by the [`lock()`] and [`try_lock()`] methods on +/// [`Mutex`]. +/// +/// [`lock()`]: struct.Mutex.html#method.lock +/// [`try_lock()`]: struct.Mutex.html#method.try_lock +/// [`Mutex`]: struct.Mutex.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] pub struct MutexGuard<'a, T: ?Sized + 'a> {