From 9577561833c0c8f7a06f282f5aaac945ca2cfec6 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Mon, 20 Apr 2015 20:45:02 -0500 Subject: [PATCH 01/13] Add two examples for Path::new --- src/libstd/path.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index e8052041aeb30..02660e98d13e6 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1240,6 +1240,13 @@ impl Path { /// use std::path::Path; /// /// Path::new("foo.txt"); + /// + /// // Strings work too + /// let s = String::from("bar.txt"); + /// let p = Path::new(&s); + /// + /// // As do other Paths + /// Path::new(&p); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new + ?Sized>(s: &S) -> &Path { From 68f8c548b38e2e1951f9770cfc9e5f646b004992 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Mon, 20 Apr 2015 21:01:13 -0500 Subject: [PATCH 02/13] Address some nits --- src/libstd/path.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 02660e98d13e6..f87f6d2dd152a 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1241,11 +1241,11 @@ impl Path { /// /// Path::new("foo.txt"); /// - /// // Strings work too + /// // Strings work too: /// let s = String::from("bar.txt"); /// let p = Path::new(&s); /// - /// // As do other Paths + /// // As do other `Path`s: /// Path::new(&p); /// ``` #[stable(feature = "rust1", since = "1.0.0")] From 4ee11f49c205e93cc5e1d93be7f127e55061aef6 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Tue, 21 Apr 2015 01:15:51 -0500 Subject: [PATCH 03/13] Separate code into two code blocks --- src/libstd/path.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index f87f6d2dd152a..a52a3dbbef9a5 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1240,12 +1240,13 @@ impl Path { /// use std::path::Path; /// /// Path::new("foo.txt"); + /// ``` + /// + /// You can create `Path`s from `String`s, or even other `Path`s: /// - /// // Strings work too: + /// ``` /// let s = String::from("bar.txt"); /// let p = Path::new(&s); - /// - /// // As do other `Path`s: /// Path::new(&p); /// ``` #[stable(feature = "rust1", since = "1.0.0")] From 41bcb828f4c2fcc0a28b8fa48467e6f51d6ab32e Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Wed, 22 Apr 2015 13:57:08 -0700 Subject: [PATCH 04/13] Explain how to create a Stdin or Stdout --- src/libstd/io/stdio.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index cd6af77daa906..42fad701533b2 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -95,6 +95,8 @@ impl Write for StderrRaw { /// /// This handle implements the `Read` trait, but beware that concurrent reads /// of `Stdin` must be executed with care. +/// +/// Created by the function `io::stdin()`. #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdin { inner: Arc>>, @@ -206,6 +208,8 @@ const OUT_MAX: usize = ::usize::MAX; /// Each handle shares a global buffer of data to be written to the standard /// output stream. Access is also synchronized via a lock and explicit control /// over locking is available via the `lock` method. +/// +/// Created by the function `io::stdout()`. #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdout { // FIXME: this should be LineWriter or BufWriter depending on the state of From db1dc5d1e6bf2c6284a3f5d0f41f5b0912bf97b1 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 26 Apr 2015 10:10:51 -0400 Subject: [PATCH 05/13] Utilize `while let` instead of `loop` with `break` in doc-comment --- src/libcollections/vec.rs | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index a8105d976e599..7f3cf77ce86ed 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -116,11 +116,7 @@ static MAX_MEMORY_SIZE: usize = isize::MAX as usize; /// stack.push(2); /// stack.push(3); /// -/// loop { -/// let top = match stack.pop() { -/// None => break, // empty -/// Some(x) => x, -/// }; +/// while let Some(top) = stack.pop() { /// // Prints 3, 2, 1 /// println!("{}", top); /// } From 7c98626cfc2a6939f52277dc1b715ea7e0edb738 Mon Sep 17 00:00:00 2001 From: Ulrik Sverdrup Date: Sun, 26 Apr 2015 22:13:58 +0200 Subject: [PATCH 06/13] collections: Improve example for as_string and as_vec --- src/libcollections/string.rs | 9 +++++---- src/libcollections/vec.rs | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index ec4df92fa890b..41ad7c2d783bd 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -950,12 +950,13 @@ impl<'a> Deref for DerefString<'a> { /// # #![feature(collections)] /// use std::string::as_string; /// -/// fn string_consumer(s: String) { -/// assert_eq!(s, "foo".to_string()); +/// // Let's pretend we have a function that requires `&String` +/// fn string_consumer(s: &String) { +/// assert_eq!(s, "foo"); /// } /// -/// let string = as_string("foo").clone(); -/// string_consumer(string); +/// // Provide a `&String` from a `&str` without allocating +/// string_consumer(&as_string("foo")); /// ``` #[unstable(feature = "collections")] pub fn as_string<'a>(x: &'a str) -> DerefString<'a> { diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 7f3cf77ce86ed..1e22f630f9b45 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -1903,6 +1903,22 @@ impl<'a, T> Drop for DerefVec<'a, T> { } /// Converts a slice to a wrapper type providing a `&Vec` reference. +/// +/// # Examples +/// +/// ``` +/// # #![feature(collections)] +/// use std::vec::as_vec; +/// +/// // Let's pretend we have a function that requires `&Vec` +/// fn vec_consumer(s: &Vec) { +/// assert_eq!(s, &[1, 2, 3]); +/// } +/// +/// // Provide a `&Vec` from a `&[i32]` without allocating +/// let values = [1, 2, 3]; +/// vec_consumer(&as_vec(&values)); +/// ``` #[unstable(feature = "collections")] pub fn as_vec<'a, T>(x: &'a [T]) -> DerefVec<'a, T> { unsafe { From 814acb8d48416318b143d7c0786291c5c7a56bac Mon Sep 17 00:00:00 2001 From: gareins Date: Sun, 26 Apr 2015 23:16:49 +0200 Subject: [PATCH 07/13] IMO better borrow_mut() documentation on RefCell Previous borrow() is enough to make borrow_mut() panic, no need to have borrow_mut() twice. [This](http://is.gd/woKKAW) --- src/libcore/cell.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs index df0de234b9a16..b4b25258bbfd6 100644 --- a/src/libcore/cell.rs +++ b/src/libcore/cell.rs @@ -417,7 +417,7 @@ impl RefCell { /// /// let result = thread::spawn(move || { /// let c = RefCell::new(5); - /// let m = c.borrow_mut(); + /// let m = c.borrow(); /// /// let b = c.borrow_mut(); // this causes a panic /// }).join(); From 0deff27c88386c11b93a0631f3ebd5ba11fef5e9 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 26 Apr 2015 17:41:16 -0400 Subject: [PATCH 08/13] Indicate function call is code-like in doc-comment --- src/libcore/iter.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index 134b84d0c7aac..a2edb97991cf3 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -179,8 +179,8 @@ pub trait Iterator { /// Creates an iterator that iterates over both this and the specified /// iterators simultaneously, yielding the two elements as pairs. When - /// either iterator returns `None`, all further invocations of next() will - /// return `None`. + /// either iterator returns `None`, all further invocations of `next()` + /// will return `None`. /// /// # Examples /// From df42cbd9a10b49794de21072a34af44b56292352 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 26 Apr 2015 23:18:19 -0400 Subject: [PATCH 09/13] Make From::from example more idiomatic / simpler --- src/libcore/convert.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 1c1ad5fd33fb8..049cd8a302ae7 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -83,10 +83,8 @@ pub trait Into: Sized { /// `String` implements `From<&str>`: /// /// ``` -/// let s = "hello"; /// let string = "hello".to_string(); -/// -/// let other_string: String = From::from(s); +/// let other_string = String::from("hello"); /// /// assert_eq!(string, other_string); /// ``` From 97e0803cff59089aa2fdc0bed97ac30a2653e5ae Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Wed, 29 Apr 2015 15:57:17 -0500 Subject: [PATCH 10/13] Improve libstd/net/udp.rs documentation. This adds some missing punctuation, adds a missing word, and corrects a bug in the description of `send_to`, which actually returns the number of bytes written on success. Fixes #24925. --- src/libstd/net/udp.rs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs index 1955b895300ea..0b04ecb1b7228 100644 --- a/src/libstd/net/udp.rs +++ b/src/libstd/net/udp.rs @@ -50,8 +50,8 @@ pub struct UdpSocket(net_imp::UdpSocket); impl UdpSocket { /// Creates a UDP socket from the given address. /// - /// Address type can be any implementor of `ToSocketAddr` trait. See its - /// documentation for concrete examples. + /// The address type can be any implementor of `ToSocketAddr` trait. See + /// its documentation for concrete examples. #[stable(feature = "rust1", since = "1.0.0")] pub fn bind(addr: A) -> io::Result { super::each_addr(addr, net_imp::UdpSocket::bind).map(UdpSocket) @@ -64,8 +64,8 @@ impl UdpSocket { self.0.recv_from(buf) } - /// Sends data on the socket to the given address. Returns nothing on - /// success. + /// Sends data on the socket to the given address. On success, returns the + /// number of bytes written. /// /// Address type can be any implementor of `ToSocketAddrs` trait. See its /// documentation for concrete examples. @@ -95,34 +95,34 @@ impl UdpSocket { self.0.duplicate().map(UdpSocket) } - /// Sets the broadcast flag on or off + /// Sets the broadcast flag on or off. pub fn set_broadcast(&self, on: bool) -> io::Result<()> { self.0.set_broadcast(on) } - /// Sets the multicast loop flag to the specified value + /// Sets the multicast loop flag to the specified value. /// /// This lets multicast packets loop back to local sockets (if enabled) pub fn set_multicast_loop(&self, on: bool) -> io::Result<()> { self.0.set_multicast_loop(on) } - /// Joins a multicast IP address (becomes a member of it) + /// Joins a multicast IP address (becomes a member of it). pub fn join_multicast(&self, multi: &IpAddr) -> io::Result<()> { self.0.join_multicast(multi) } - /// Leaves a multicast IP address (drops membership from it) + /// Leaves a multicast IP address (drops membership from it). pub fn leave_multicast(&self, multi: &IpAddr) -> io::Result<()> { self.0.leave_multicast(multi) } - /// Sets the multicast TTL + /// Sets the multicast TTL. pub fn set_multicast_time_to_live(&self, ttl: i32) -> io::Result<()> { self.0.multicast_time_to_live(ttl) } - /// Sets this socket's TTL + /// Sets this socket's TTL. pub fn set_time_to_live(&self, ttl: i32) -> io::Result<()> { self.0.time_to_live(ttl) } From 7b1ff617872c94226830a12dc3bb45312e56fabc Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Wed, 29 Apr 2015 16:19:35 -0500 Subject: [PATCH 11/13] Add some missing punctuation in the libstd/net/ip.rs docs. --- src/libstd/net/ip.rs | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 065126c6fdbb5..9fd69840f7f05 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -60,7 +60,7 @@ pub enum Ipv6MulticastScope { impl Ipv4Addr { /// Creates a new IPv4 address from four eight-bit octets. /// - /// The result will represent the IP address a.b.c.d + /// The result will represent the IP address `a`.`b`.`c`.`d`. #[stable(feature = "rust1", since = "1.0.0")] pub fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr { Ipv4Addr { @@ -73,19 +73,19 @@ impl Ipv4Addr { } } - /// Returns the four eight-bit integers that make up this address + /// Returns the four eight-bit integers that make up this address. #[stable(feature = "rust1", since = "1.0.0")] pub fn octets(&self) -> [u8; 4] { let bits = ntoh(self.inner.s_addr); [(bits >> 24) as u8, (bits >> 16) as u8, (bits >> 8) as u8, bits as u8] } - /// Returns true for the special 'unspecified' address 0.0.0.0 + /// Returns true for the special 'unspecified' address 0.0.0.0. pub fn is_unspecified(&self) -> bool { self.inner.s_addr == 0 } - /// Returns true if this is a loopback address (127.0.0.0/8) + /// Returns true if this is a loopback address (127.0.0.0/8). pub fn is_loopback(&self) -> bool { self.octets()[0] == 127 } @@ -106,7 +106,7 @@ impl Ipv4Addr { } } - /// Returns true if the address is link-local (169.254.0.0/16) + /// Returns true if the address is link-local (169.254.0.0/16). pub fn is_link_local(&self) -> bool { self.octets()[0] == 169 && self.octets()[1] == 254 } @@ -116,7 +116,7 @@ impl Ipv4Addr { /// Non-globally-routable networks include the private networks (10.0.0.0/8, /// 172.16.0.0/12 and 192.168.0.0/16), the loopback network (127.0.0.0/8), /// the link-local network (169.254.0.0/16), the broadcast address (255.255.255.255/32) and - /// the test networks used for documentation (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24) + /// the test networks used for documentation (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24). pub fn is_global(&self) -> bool { !self.is_private() && !self.is_loopback() && !self.is_link_local() && !self.is_broadcast() && !self.is_documentation() @@ -131,13 +131,13 @@ impl Ipv4Addr { /// Returns true if this is a broadcast address. /// - /// A broadcast address has all octets set to 255 as defined in RFC 919 + /// A broadcast address has all octets set to 255 as defined in RFC 919. pub fn is_broadcast(&self) -> bool { self.octets()[0] == 255 && self.octets()[1] == 255 && self.octets()[2] == 255 && self.octets()[3] == 255 } - /// Returns true if this address is in a range designated for documentation + /// Returns true if this address is in a range designated for documentation. /// /// This is defined in RFC 5737 /// - 192.0.2.0/24 (TEST-NET-1) @@ -152,7 +152,7 @@ impl Ipv4Addr { } } - /// Converts this address to an IPv4-compatible IPv6 address + /// Converts this address to an IPv4-compatible IPv6 address. /// /// a.b.c.d becomes ::a.b.c.d #[stable(feature = "rust1", since = "1.0.0")] @@ -162,7 +162,7 @@ impl Ipv4Addr { ((self.octets()[2] as u16) << 8) | self.octets()[3] as u16) } - /// Converts this address to an IPv4-mapped IPv6 address + /// Converts this address to an IPv4-mapped IPv6 address. /// /// a.b.c.d becomes ::ffff:a.b.c.d #[stable(feature = "rust1", since = "1.0.0")] @@ -247,7 +247,7 @@ impl FromInner for Ipv4Addr { impl Ipv6Addr { /// Creates a new IPv6 address from eight 16-bit segments. /// - /// The result will represent the IP address a:b:c:d:e:f:g:h + /// The result will represent the IP address a:b:c:d:e:f:g:h. #[stable(feature = "rust1", since = "1.0.0")] pub fn new(a: u16, b: u16, c: u16, d: u16, e: u16, f: u16, g: u16, h: u16) -> Ipv6Addr { @@ -259,7 +259,7 @@ impl Ipv6Addr { } } - /// Returns the eight 16-bit segments that make up this address + /// Returns the eight 16-bit segments that make up this address. #[stable(feature = "rust1", since = "1.0.0")] pub fn segments(&self) -> [u16; 8] { [ntoh(self.inner.s6_addr[0]), @@ -272,12 +272,12 @@ impl Ipv6Addr { ntoh(self.inner.s6_addr[7])] } - /// Returns true for the special 'unspecified' address :: + /// Returns true for the special 'unspecified' address ::. pub fn is_unspecified(&self) -> bool { self.segments() == [0, 0, 0, 0, 0, 0, 0, 0] } - /// Returns true if this is a loopback address (::1) + /// Returns true if this is a loopback address (::1). pub fn is_loopback(&self) -> bool { self.segments() == [0, 0, 0, 0, 0, 0, 0, 1] } @@ -295,25 +295,25 @@ impl Ipv6Addr { } } - /// Returns true if this is a unique local address (IPv6) + /// Returns true if this is a unique local address (IPv6). /// - /// Unique local addresses are defined in RFC4193 and have the form fc00::/7 + /// Unique local addresses are defined in RFC4193 and have the form fc00::/7. pub fn is_unique_local(&self) -> bool { (self.segments()[0] & 0xfe00) == 0xfc00 } - /// Returns true if the address is unicast and link-local (fe80::/10) + /// Returns true if the address is unicast and link-local (fe80::/10). pub fn is_unicast_link_local(&self) -> bool { (self.segments()[0] & 0xffc0) == 0xfe80 } /// Returns true if this is a deprecated unicast site-local address (IPv6 - /// fec0::/10) + /// fec0::/10). pub fn is_unicast_site_local(&self) -> bool { (self.segments()[0] & 0xffc0) == 0xfec0 } - /// Returns true if the address is a globally routable unicast address + /// Returns true if the address is a globally routable unicast address. /// /// Non-globally-routable unicast addresses include the loopback address, /// the link-local addresses, the deprecated site-local addresses and the From f850f59d14b5539fe03431736bc652977e2a5ed7 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Wed, 29 Apr 2015 16:21:39 -0500 Subject: [PATCH 12/13] Add some missing punctuation in the libstd/net/tcp.rs docs. --- src/libstd/net/tcp.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index e48d0e6008b87..130e1eee8f924 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -125,7 +125,7 @@ impl TcpStream { self.0.duplicate().map(TcpStream) } - /// Sets the nodelay flag on this connection to the boolean specified + /// Sets the nodelay flag on this connection to the boolean specified. pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> { self.0.set_nodelay(nodelay) } From 957e42a1c652a0d4b51bc16b5760977cc79dc0c1 Mon Sep 17 00:00:00 2001 From: Nick Hamann Date: Wed, 29 Apr 2015 16:24:44 -0500 Subject: [PATCH 13/13] Improve libstd/net/addr.rs documentation. This adds some missing punctuation and converts uses of "Gets" to "Returns". This sounds better to my ear, but more importantly is more consistent with the documentation from other files. --- src/libstd/net/addr.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 2e34e46726fb2..b0bf9d0f80626 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -41,7 +41,7 @@ pub enum SocketAddr { #[stable(feature = "rust1", since = "1.0.0")] pub struct SocketAddrV4 { inner: libc::sockaddr_in } -/// An IPv6 socket address +/// An IPv6 socket address. #[derive(Copy)] #[stable(feature = "rust1", since = "1.0.0")] pub struct SocketAddrV6 { inner: libc::sockaddr_in6 } @@ -56,7 +56,7 @@ impl SocketAddr { } } - /// Gets the IP address associated with this socket address. + /// Returns the IP address associated with this socket address. #[unstable(feature = "ip_addr", reason = "recent addition")] pub fn ip(&self) -> IpAddr { match *self { @@ -65,7 +65,7 @@ impl SocketAddr { } } - /// Gets the port number associated with this socket address + /// Returns the port number associated with this socket address. #[stable(feature = "rust1", since = "1.0.0")] pub fn port(&self) -> u16 { match *self { @@ -89,7 +89,7 @@ impl SocketAddrV4 { } } - /// Gets the IP address associated with this socket address. + /// Returns the IP address associated with this socket address. #[stable(feature = "rust1", since = "1.0.0")] pub fn ip(&self) -> &Ipv4Addr { unsafe { @@ -97,7 +97,7 @@ impl SocketAddrV4 { } } - /// Gets the port number associated with this socket address + /// Returns the port number associated with this socket address. #[stable(feature = "rust1", since = "1.0.0")] pub fn port(&self) -> u16 { ntoh(self.inner.sin_port) } } @@ -120,7 +120,7 @@ impl SocketAddrV6 { } } - /// Gets the IP address associated with this socket address. + /// Returns the IP address associated with this socket address. #[stable(feature = "rust1", since = "1.0.0")] pub fn ip(&self) -> &Ipv6Addr { unsafe { @@ -128,16 +128,16 @@ impl SocketAddrV6 { } } - /// Gets the port number associated with this socket address + /// Returns the port number associated with this socket address. #[stable(feature = "rust1", since = "1.0.0")] pub fn port(&self) -> u16 { ntoh(self.inner.sin6_port) } - /// Gets scope ID associated with this address, corresponding to the + /// Returns scope ID associated with this address, corresponding to the /// `sin6_flowinfo` field in C. #[stable(feature = "rust1", since = "1.0.0")] pub fn flowinfo(&self) -> u32 { ntoh(self.inner.sin6_flowinfo) } - /// Gets scope ID associated with this address, corresponding to the + /// Returns scope ID associated with this address, corresponding to the /// `sin6_scope_id` field in C. #[stable(feature = "rust1", since = "1.0.0")] pub fn scope_id(&self) -> u32 { ntoh(self.inner.sin6_scope_id) }