Merge pull request #25273 from steveklabnik/second_doc_backport

Second doc backport

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> {

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);
 /// }
@@ -1907,6 +1903,22 @@ impl<'a, T> Drop for DerefVec<'a, T> {
 }
 
 /// Converts a slice to a wrapper type providing a `&Vec<T>` reference.
+///
+/// # Examples
+///
+/// ```
+/// # #![feature(collections)]
+/// use std::vec::as_vec;
+///
+/// // Let's pretend we have a function that requires `&Vec<i32>`
+/// fn vec_consumer(s: &Vec<i32>) {
+///     assert_eq!(s, &[1, 2, 3]);
+/// }
+///
+/// // Provide a `&Vec<i32>` 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 {

src/libcore/cell.rs

@@ -417,7 +417,7 @@ impl<T> RefCell<T> {
     ///
     /// 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();

src/libcore/convert.rs

@@ -83,10 +83,8 @@ pub trait Into<T>: 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);
 /// ```

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
     ///

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<Mutex<BufReader<StdinRaw>>>,
@@ -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

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,15 +89,15 @@ 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 {
             &*(&self.inner.sin_addr as *const libc::in_addr as *const Ipv4Addr)
         }
     }
 
-    /// 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,24 +120,24 @@ 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 {
             &*(&self.inner.sin6_addr as *const libc::in6_addr as *const Ipv6Addr)
         }
     }
 
-    /// 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) }

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<libc::in_addr> 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

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)
     }

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<A: ToSocketAddrs>(addr: A) -> io::Result<UdpSocket> {
         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)
     }