From 9976f5f7c551edb557b0f4633dfcd772cf040a2b Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 7 Dec 2016 16:20:53 -0800 Subject: [PATCH 01/14] Add missing doc examples for SocketAddr struct --- src/libstd/sys/unix/ext/net.rs | 36 ++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index 80f53da1cefe0..47a803424b534 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -85,6 +85,21 @@ enum AddressKind<'a> { } /// An address associated with a Unix socket. +/// +/// # Examples +/// +/// ``` +/// use std::os::unix::net::UnixListener; +/// +/// let socket = match UnixListener::bind("/tmp/sock") { +/// Ok(sock) => sock, +/// Err(e) => { +/// println!("Couldn't bind: {:?}", e); +/// return +/// } +/// }; +/// let addr = socket.local_addr().expect("Couldn't get local address"); +/// ``` #[derive(Clone)] #[stable(feature = "unix_socket", since = "1.10.0")] pub struct SocketAddr { @@ -121,6 +136,16 @@ impl SocketAddr { } /// Returns true if and only if the address is unnamed. + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixListener; + /// + /// let socket = match UnixListener::bind("/tmp/sock").unwrap(); + /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// assert_eq!(addr.is_unnamed(), false); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn is_unnamed(&self) -> bool { if let AddressKind::Unnamed = self.address() { @@ -131,6 +156,17 @@ impl SocketAddr { } /// Returns the contents of this address if it is a `pathname` address. + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixListener; + /// use std::path::Path; + /// + /// let socket = match UnixListener::bind("/tmp/sock").unwrap(); + /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// assert_eq!(addr.as_pathname(), Some(Path::new("/tmp/sock"))); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn as_pathname(&self) -> Option<&Path> { if let AddressKind::Pathname(path) = self.address() { From 7fe17f96d5acf5753e05414748cf3e1f63371c81 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 7 Dec 2016 18:09:39 -0800 Subject: [PATCH 02/14] Add doc examples for UnixStream --- src/libstd/sys/unix/ext/net.rs | 151 +++++++++++++++++++++++++++++++-- 1 file changed, 145 insertions(+), 6 deletions(-) diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index 47a803424b534..69954d91857af 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -218,7 +218,7 @@ impl<'a> fmt::Display for AsciiEscaped<'a> { /// /// # Examples /// -/// ```rust,no_run +/// ```no_run /// use std::os::unix::net::UnixStream; /// use std::io::prelude::*; /// @@ -248,6 +248,20 @@ impl fmt::Debug for UnixStream { impl UnixStream { /// Connects to the socket named by `path`. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// + /// let socket = match UnixStream::connect("/tmp/sock") { + /// Ok(sock) => sock, + /// Err(e) => { + /// println!("Couldn't connect: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn connect>(path: P) -> io::Result { fn inner(path: &Path) -> io::Result { @@ -265,6 +279,20 @@ impl UnixStream { /// Creates an unnamed pair of connected sockets. /// /// Returns two `UnixStream`s which are connected to each other. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// + /// let (sock1, sock2) = match UnixStream::pair() { + /// Ok((sock1, sock2)) => (sock1, sock2), + /// Err(e) => { + /// println!("Couldn't create a pair of sockets: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn pair() -> io::Result<(UnixStream, UnixStream)> { let (i1, i2) = Socket::new_pair(libc::AF_UNIX, libc::SOCK_STREAM)?; @@ -277,18 +305,45 @@ impl UnixStream { /// object references. Both handles will read and write the same stream of /// data, and options set on one stream will be propogated to the other /// stream. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let sock_copy = socket.try_clone().expect("Couldn't clone socket..."); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn try_clone(&self) -> io::Result { self.0.duplicate().map(UnixStream) } /// Returns the socket address of the local half of this connection. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn local_addr(&self) -> io::Result { SocketAddr::new(|addr, len| unsafe { libc::getsockname(*self.0.as_inner(), addr, len) }) } /// Returns the socket address of the remote half of this connection. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let addr = socket.peer_addr().expect("Couldn't get peer address"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn peer_addr(&self) -> io::Result { SocketAddr::new(|addr, len| unsafe { libc::getpeername(*self.0.as_inner(), addr, len) }) @@ -296,9 +351,23 @@ impl UnixStream { /// Sets the read timeout for the socket. /// - /// If the provided value is `None`, then `read` calls will block - /// indefinitely. It is an error to pass the zero `Duration` to this + /// If the provided value is [`None`], then [`read()`] calls will block + /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`read()`]: ../../std/io/trait.Read.html#tymethod.read + /// [`Duration`]: ../../std/time/struct.Duration.html + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// socket.set_read_timeout(Some(Duration::new(1, 0))).expect("Couldn't set read timeout"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_read_timeout(&self, timeout: Option) -> io::Result<()> { self.0.set_timeout(timeout, libc::SO_RCVTIMEO) @@ -306,33 +375,91 @@ impl UnixStream { /// Sets the write timeout for the socket. /// - /// If the provided value is `None`, then `write` calls will block - /// indefinitely. It is an error to pass the zero `Duration` to this + /// If the provided value is [`None`], then [`write()`] calls will block + /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`read()`]: ../../std/io/trait.Write.html#tymethod.write + /// [`Duration`]: ../../std/time/struct.Duration.html + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// socket.set_write_timeout(Some(Duration::new(1, 0))).expect("Couldn't set write timeout"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_write_timeout(&self, timeout: Option) -> io::Result<()> { self.0.set_timeout(timeout, libc::SO_SNDTIMEO) } /// Returns the read timeout of this socket. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// socket.set_read_timeout(Some(Duration::new(1, 0))).expect("Couldn't set read timeout"); + /// assert_eq!(socket.read_timeout().unwrap(), Some(Duration::new(1, 0))); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn read_timeout(&self) -> io::Result> { self.0.timeout(libc::SO_RCVTIMEO) } /// Returns the write timeout of this socket. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// socket.set_write_timeout(Some(Duration::new(1, 0))).expect("Couldn't set write timeout"); + /// assert_eq!(socket.write_timeout().unwrap(), Some(Duration::new(1, 0))); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn write_timeout(&self) -> io::Result> { self.0.timeout(libc::SO_SNDTIMEO) } /// Moves the socket into or out of nonblocking mode. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// socket.set_nonblocking(true).expect("Couldn't set non blocking"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { self.0.set_nonblocking(nonblocking) } /// Returns the value of the `SO_ERROR` option. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// if let Ok(Some(err)) = socket.take_error() { + /// println!("Got error: {:?}", err); + /// } + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn take_error(&self) -> io::Result> { self.0.take_error() @@ -342,7 +469,19 @@ impl UnixStream { /// /// This function will cause all pending and future I/O calls on the /// specified portions to immediately return with an appropriate value - /// (see the documentation of `Shutdown`). + /// (see the documentation of [`Shutdown`]). + /// + /// [`Shutdown`]: ../../std/net/enum.Shutdown.html + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixStream; + /// use std::time::Duration; + /// + /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// socket.shutdown(Shutdown::Both).expect("shutdown function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { self.0.shutdown(how) From c35b9f6703e11e08d5250434472b36a109353cc3 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 7 Dec 2016 18:26:54 -0800 Subject: [PATCH 03/14] Add UnixListener doc examples --- src/libstd/sys/unix/ext/net.rs | 111 ++++++++++++++++++++++++++++++--- 1 file changed, 101 insertions(+), 10 deletions(-) diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index 69954d91857af..f346e3eb44f05 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -437,7 +437,6 @@ impl UnixStream { /// /// ```no_run /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; /// /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); /// socket.set_nonblocking(true).expect("Couldn't set non blocking"); @@ -453,7 +452,6 @@ impl UnixStream { /// /// ```no_run /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; /// /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); /// if let Ok(Some(err)) = socket.take_error() { @@ -477,7 +475,6 @@ impl UnixStream { /// /// ```no_run /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; /// /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); /// socket.shutdown(Shutdown::Both).expect("shutdown function failed"); @@ -557,7 +554,7 @@ impl IntoRawFd for UnixStream { /// /// # Examples /// -/// ```rust,no_run +/// ```no_run /// use std::thread; /// use std::os::unix::net::{UnixStream, UnixListener}; /// @@ -580,9 +577,6 @@ impl IntoRawFd for UnixStream { /// } /// } /// } -/// -/// // close the listener socket -/// drop(listener); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub struct UnixListener(Socket); @@ -601,6 +595,20 @@ impl fmt::Debug for UnixListener { impl UnixListener { /// Creates a new `UnixListener` bound to the specified socket. + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixListener; + /// + /// let listener = match UnixListener::bind("/path/to/the/socket") { + /// Ok(sock) => sock, + /// Err(e) => { + /// println!("Couldn't connect: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn bind>(path: P) -> io::Result { fn inner(path: &Path) -> io::Result { @@ -620,8 +628,23 @@ impl UnixListener { /// Accepts a new incoming connection to this listener. /// /// This function will block the calling thread until a new Unix connection - /// is established. When established, the corersponding `UnixStream` and + /// is established. When established, the corersponding [`UnixStream`] and /// the remote peer's address will be returned. + /// + /// [`UnixStream`]: ../../std/os/unix/net/struct.UnixStream.html + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixListener; + /// + /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); + /// + /// match listener.accept() { + /// Ok((socket, addr)) => println!("Got a client: {:?}", addr), + /// Err(e) => println!("accept function failed: {:?}", e), + /// } + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn accept(&self) -> io::Result<(UnixStream, SocketAddr)> { let mut storage: libc::sockaddr_un = unsafe { mem::zeroed() }; @@ -636,24 +659,65 @@ impl UnixListener { /// The returned `UnixListener` is a reference to the same socket that this /// object references. Both handles can be used to accept incoming /// connections and options set on one listener will affect the other. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixListener; + /// + /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); + /// + /// let listener_copy = listener.try_clone().expect("try_clone failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn try_clone(&self) -> io::Result { self.0.duplicate().map(UnixListener) } /// Returns the local socket address of this listener. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixListener; + /// + /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); + /// + /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn local_addr(&self) -> io::Result { SocketAddr::new(|addr, len| unsafe { libc::getsockname(*self.0.as_inner(), addr, len) }) } /// Moves the socket into or out of nonblocking mode. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixListener; + /// + /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); + /// + /// socket.set_nonblocking(true).expect("Couldn't set non blocking"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { self.0.set_nonblocking(nonblocking) } /// Returns the value of the `SO_ERROR` option. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixListener; + /// + /// let socket = match UnixListener::bind("/tmp/sock").unwrap(); + /// if let Ok(Some(err)) = socket.take_error() { + /// println!("Got error: {:?}", err); + /// } + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn take_error(&self) -> io::Result> { self.0.take_error() @@ -661,8 +725,35 @@ impl UnixListener { /// Returns an iterator over incoming connections. /// - /// The iterator will never return `None` and will also not yield the - /// peer's `SocketAddr` structure. + /// The iterator will never return [`None`] and will also not yield the + /// peer's [`SocketAddr`] structure. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`SocketAddr`]: struct.SocketAddr.html + /// + /// # Examples + /// + /// ```no_run + /// use std::thread; + /// use std::os::unix::net::{UnixStream, UnixListener}; + /// + /// fn handle_client(stream: UnixStream) { + /// // ... + /// } + /// + /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); + /// + /// for stream in listener.incoming() { + /// match stream { + /// Ok(stream) => { + /// thread::spawn(|| handle_client(stream)); + /// } + /// Err(err) => { + /// break; + /// } + /// } + /// } + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn incoming<'a>(&'a self) -> Incoming<'a> { Incoming { listener: self } From a78a33c52a3a4766e170a8dbe0328cbbd03d4f14 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 7 Dec 2016 18:28:07 -0800 Subject: [PATCH 04/14] Add Incoming doc examples --- src/libstd/sys/unix/ext/net.rs | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index f346e3eb44f05..d49f9343b0e77 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -791,9 +791,36 @@ impl<'a> IntoIterator for &'a UnixListener { } } -/// An iterator over incoming connections to a `UnixListener`. +/// An iterator over incoming connections to a [`UnixListener`]. /// -/// It will never return `None`. +/// It will never return [`None`]. +/// +/// [`None`]: ../../std/option/enum.Option.html#variant.None +/// [`UnixListener`]: struct.UnixListener.html +/// +/// # Examples +/// +/// ```no_run +/// use std::thread; +/// use std::os::unix::net::{UnixStream, UnixListener}; +/// +/// fn handle_client(stream: UnixStream) { +/// // ... +/// } +/// +/// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); +/// +/// for stream in listener.incoming() { +/// match stream { +/// Ok(stream) => { +/// thread::spawn(|| handle_client(stream)); +/// } +/// Err(err) => { +/// break; +/// } +/// } +/// } +/// ``` #[derive(Debug)] #[stable(feature = "unix_socket", since = "1.10.0")] pub struct Incoming<'a> { @@ -817,7 +844,7 @@ impl<'a> Iterator for Incoming<'a> { /// /// # Examples /// -/// ```rust,no_run +/// ```no_run /// use std::os::unix::net::UnixDatagram; /// /// let socket = UnixDatagram::bind("/path/to/my/socket").unwrap(); From 83231859417efc363d6929b58d75cdcf40bb5f2d Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Wed, 7 Dec 2016 16:37:38 +0800 Subject: [PATCH 05/14] minor fix about visibility in reference --- src/doc/reference.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index bf286aaec4bb3..ce3fef982b962 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -1731,7 +1731,8 @@ of an item to see whether it should be allowed or not. This is where privacy warnings are generated, or otherwise "you used a private item of another module and weren't allowed to." -By default, everything in Rust is *private*, with one exception. Enum variants +By default, everything in Rust is *private*, with two exceptions: Associated +items of a Trait are public by default; Enum variants in a `pub` enum are also public by default. When an item is declared as `pub`, it can be thought of as being accessible to the outside world. For example: From e095c710f73ae98cdc769a3e7992d3a44e91bb8f Mon Sep 17 00:00:00 2001 From: Liigo Date: Tue, 13 Dec 2016 20:21:00 +0800 Subject: [PATCH 06/14] Associated items and variants inherit visibility from their traits and enums respectively. --- src/doc/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/reference.md b/src/doc/reference.md index ce3fef982b962..b5a91a170d8ed 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -1732,7 +1732,7 @@ warnings are generated, or otherwise "you used a private item of another module and weren't allowed to." By default, everything in Rust is *private*, with two exceptions: Associated -items of a Trait are public by default; Enum variants +items in a `pub` Trait are public by default; Enum variants in a `pub` enum are also public by default. When an item is declared as `pub`, it can be thought of as being accessible to the outside world. For example: From 16d4b7b0e5d011c69b41a4a0a440193544795f5e Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Sat, 3 Dec 2016 13:05:05 -0800 Subject: [PATCH 07/14] doc: Explain meaning of Result iters and link to factory functions. --- src/libcore/result.rs | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/src/libcore/result.rs b/src/libcore/result.rs index afed99d265f19..99c407e5273ea 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -501,6 +501,8 @@ impl Result { /// Returns an iterator over the possibly contained value. /// + /// The iterator yields one value if the result is [`Ok`], otherwise none. + /// /// # Examples /// /// Basic usage: @@ -512,6 +514,8 @@ impl Result { /// let x: Result = Err("nothing!"); /// assert_eq!(x.iter().next(), None); /// ``` + /// + /// [`Ok`]: enum.Result.html#variant.Ok #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn iter(&self) -> Iter { @@ -520,6 +524,8 @@ impl Result { /// Returns a mutable iterator over the possibly contained value. /// + /// The iterator yields one value if the result is [`Ok`], otherwise none. + /// /// # Examples /// /// Basic usage: @@ -535,6 +541,8 @@ impl Result { /// let mut x: Result = Err("nothing!"); /// assert_eq!(x.iter_mut().next(), None); /// ``` + /// + /// [`Ok`]: enum.Result.html#variant.Ok #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub fn iter_mut(&mut self) -> IterMut { @@ -848,6 +856,8 @@ impl IntoIterator for Result { /// Returns a consuming iterator over the possibly contained value. /// + /// The iterator yields one value if the result is [`Ok`], otherwise none. + /// /// # Examples /// /// Basic usage: @@ -861,6 +871,8 @@ impl IntoIterator for Result { /// let v: Vec = x.into_iter().collect(); /// assert_eq!(v, []); /// ``` + /// + /// [`Ok`]: enum.Result.html#variant.Ok #[inline] fn into_iter(self) -> IntoIter { IntoIter { inner: self.ok() } @@ -893,8 +905,13 @@ impl<'a, T, E> IntoIterator for &'a mut Result { /// An iterator over a reference to the [`Ok`] variant of a [`Result`]. /// +/// The iterator yields one value if the result is [`Ok`], otherwise none. +/// +/// Created by [`Result::iter`]. +/// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Result`]: enum.Result.html +/// [`Result::iter`]: enum.Result.html#method.iter #[derive(Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct Iter<'a, T: 'a> { inner: Option<&'a T> } @@ -934,8 +951,11 @@ impl<'a, T> Clone for Iter<'a, T> { /// An iterator over a mutable reference to the [`Ok`] variant of a [`Result`]. /// +/// Created by [`Result::iter_mut`]. +/// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Result`]: enum.Result.html +/// [`Result::iter_mut`]: enum.Result.html#method.iter_mut #[derive(Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct IterMut<'a, T: 'a> { inner: Option<&'a mut T> } @@ -968,9 +988,12 @@ impl<'a, T> FusedIterator for IterMut<'a, T> {} #[unstable(feature = "trusted_len", issue = "37572")] unsafe impl<'a, A> TrustedLen for IterMut<'a, A> {} -/// An iterator over the value in a [`Ok`] variant of a [`Result`]. This struct is -/// created by the [`into_iter`] method on [`Result`][`Result`] (provided by -/// the [`IntoIterator`] trait). +/// An iterator over the value in a [`Ok`] variant of a [`Result`]. +/// +/// The iterator yields one value if the result is [`Ok`], otherwise none. +/// +/// This struct is created by the [`into_iter`] method on +/// [`Result`][`Result`] (provided by the [`IntoIterator`] trait). /// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Result`]: enum.Result.html From 60fbe7a5e336feb757203ce95c40144f59d44842 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 13 Dec 2016 14:03:36 +0100 Subject: [PATCH 08/14] Add missing Duration examples --- src/libstd/time/duration.rs | 79 +++++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 13 deletions(-) diff --git a/src/libstd/time/duration.rs b/src/libstd/time/duration.rs index 41d675b6f88fc..162ce530f17cd 100644 --- a/src/libstd/time/duration.rs +++ b/src/libstd/time/duration.rs @@ -14,16 +14,19 @@ const NANOS_PER_SEC: u32 = 1_000_000_000; const NANOS_PER_MILLI: u32 = 1_000_000; const MILLIS_PER_SEC: u64 = 1_000; -/// A duration type to represent a span of time, typically used for system +/// A `Duration` type to represent a span of time, typically used for system /// timeouts. /// -/// Each duration is composed of a number of seconds and nanosecond precision. +/// Each `Duration` is composed of a number of seconds and nanosecond precision. /// APIs binding a system timeout will typically round up the nanosecond /// precision if the underlying system does not support that level of precision. /// -/// Durations implement many common traits, including `Add`, `Sub`, and other -/// ops traits. Currently a duration may only be inspected for its number of -/// seconds and its nanosecond precision. +/// `Duration`s implement many common traits, including [`Add`], [`Sub`], and other +/// [`ops`] traits. +/// +/// [`Add`]: ../../std/ops/trait.Add.html +/// [`Sub`]: ../../std/ops/trait.Sub.html +/// [`ops`]: ../../std/ops/index.html /// /// # Examples /// @@ -56,6 +59,14 @@ impl Duration { /// /// This constructor will panic if the carry from the nanoseconds overflows /// the seconds counter. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let five_seconds = Duration::new(5, 0); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn new(secs: u64, nanos: u32) -> Duration { @@ -66,6 +77,14 @@ impl Duration { } /// Creates a new `Duration` from the specified number of seconds. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let five_seconds = Duration::from_secs(5); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn from_secs(secs: u64) -> Duration { @@ -73,6 +92,14 @@ impl Duration { } /// Creates a new `Duration` from the specified number of milliseconds. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let five_seconds = Duration::from_millis(5000); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn from_millis(millis: u64) -> Duration { @@ -81,26 +108,46 @@ impl Duration { Duration { secs: secs, nanos: nanos } } - /// Returns the number of whole seconds represented by this duration. + /// Returns the number of whole seconds represented by this `Duration`. /// /// The extra precision represented by this duration is ignored (i.e. extra /// nanoseconds are not represented in the returned value). + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let five_seconds = Duration::new(5, 0); + /// assert_eq!(five_seconds.as_secs(), 5); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn as_secs(&self) -> u64 { self.secs } - /// Returns the nanosecond precision represented by this duration. + /// Returns the nanosecond precision represented by this `Duration`. /// /// This method does **not** return the length of the duration when /// represented by nanoseconds. The returned number always represents a /// fractional portion of a second (i.e. it is less than one billion). + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let duration = Duration::from_millis(5010); + /// assert_eq!(duration.subsec_nanos(), 10000000); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn subsec_nanos(&self) -> u32 { self.nanos } - /// Checked duration addition. Computes `self + other`, returning `None` + /// Checked `Duration` addition. Computes `self + other`, returning [`None`] /// if overflow occurred. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -136,9 +183,11 @@ impl Duration { } } - /// Checked duration subtraction. Computes `self + other`, returning `None` + /// Checked `Duration` subtraction. Computes `self - other`, returning [`None`] /// if the result would be negative or if underflow occurred. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: @@ -172,8 +221,10 @@ impl Duration { } } - /// Checked duration multiplication. Computes `self * other`, returning - /// `None` if underflow or overflow occurred. + /// Checked `Duration` multiplication. Computes `self * other`, returning + /// [`None`] if overflow occurred. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// @@ -207,8 +258,10 @@ impl Duration { } } - /// Checked duration division. Computes `self / other`, returning `None` - /// if `other == 0` or the operation results in underflow or overflow. + /// Checked `Duration` division. Computes `self / other`, returning [`None`] + /// if `other == 0`. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// From 8cd3081b5ac0e3c2594e5e89b615f5e92625eaae Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 15 Dec 2016 20:42:10 +0200 Subject: [PATCH 09/14] rustdoc: a formatting nit --- src/librustdoc/lib.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 174118db93e0b..835825d31eec9 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -259,10 +259,11 @@ pub fn main_args(args: &[String]) -> isize { } let external_html = match ExternalHtml::load( - &matches.opt_strs("html-in-header"), &matches.opt_strs("html-before-content"), + &matches.opt_strs("html-in-header"), + &matches.opt_strs("html-before-content"), &matches.opt_strs("html-after-content")) { Some(eh) => eh, - None => return 3 + None => return 3, }; let crate_name = matches.opt_str("crate-name"); let playground_url = matches.opt_str("playground-url"); From 2938e6a41172d1c71f5c58e9a71958f2d5c1a262 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 7 Dec 2016 21:55:09 -0800 Subject: [PATCH 10/14] Add missing doc examples for UnixDatagram --- src/libstd/sys/unix/ext/net.rs | 323 +++++++++++++++++++++++++++++---- 1 file changed, 285 insertions(+), 38 deletions(-) diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index d49f9343b0e77..e822488c01851 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -139,13 +139,25 @@ impl SocketAddr { /// /// # Examples /// + /// A named address: + /// /// ``` /// use std::os::unix::net::UnixListener; /// - /// let socket = match UnixListener::bind("/tmp/sock").unwrap(); + /// let socket = UnixListener::bind("/tmp/sock").unwrap(); /// let addr = socket.local_addr().expect("Couldn't get local address"); /// assert_eq!(addr.is_unnamed(), false); /// ``` + /// + /// An unnamed address: + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// + /// let socket = UnixDatagram::unbound().unwrap(); + /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// assert_eq!(addr.is_unnamed(), true); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn is_unnamed(&self) -> bool { if let AddressKind::Unnamed = self.address() { @@ -159,14 +171,27 @@ impl SocketAddr { /// /// # Examples /// + /// With a pathname: + /// /// ``` /// use std::os::unix::net::UnixListener; /// use std::path::Path; /// - /// let socket = match UnixListener::bind("/tmp/sock").unwrap(); + /// let socket = UnixListener::bind("/tmp/sock").unwrap(); /// let addr = socket.local_addr().expect("Couldn't get local address"); /// assert_eq!(addr.as_pathname(), Some(Path::new("/tmp/sock"))); /// ``` + /// + /// Without a pathname: + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// use std::path::Path; + /// + /// let socket = UnixDatagram::unbound().unwrap(); + /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// assert_eq!(addr.as_pathname(), None); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn as_pathname(&self) -> Option<&Path> { if let AddressKind::Pathname(path) = self.address() { @@ -311,8 +336,8 @@ impl UnixStream { /// ```no_run /// use std::os::unix::net::UnixStream; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); - /// let sock_copy = socket.try_clone().expect("Couldn't clone socket..."); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); + /// let sock_copy = socket.try_clone().expect("Couldn't clone socket"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn try_clone(&self) -> io::Result { @@ -326,7 +351,7 @@ impl UnixStream { /// ```no_run /// use std::os::unix::net::UnixStream; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// let addr = socket.local_addr().expect("Couldn't get local address"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] @@ -341,7 +366,7 @@ impl UnixStream { /// ```no_run /// use std::os::unix::net::UnixStream; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// let addr = socket.peer_addr().expect("Couldn't get peer address"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] @@ -355,9 +380,9 @@ impl UnixStream { /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// - /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../std/io/trait.Read.html#tymethod.read - /// [`Duration`]: ../../std/time/struct.Duration.html + /// [`None`]: ../../../../std/option/enum.Option.html#variant.None + /// [`read()`]: ../../../../std/io/trait.Read.html#tymethod.read + /// [`Duration`]: ../../../../std/time/struct.Duration.html /// /// # Examples /// @@ -365,7 +390,7 @@ impl UnixStream { /// use std::os::unix::net::UnixStream; /// use std::time::Duration; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// socket.set_read_timeout(Some(Duration::new(1, 0))).expect("Couldn't set read timeout"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] @@ -379,9 +404,9 @@ impl UnixStream { /// indefinitely. It is an error to pass the zero [`Duration`] to this /// method. /// - /// [`None`]: ../../std/option/enum.Option.html#variant.None - /// [`read()`]: ../../std/io/trait.Write.html#tymethod.write - /// [`Duration`]: ../../std/time/struct.Duration.html + /// [`None`]: ../../../../std/option/enum.Option.html#variant.None + /// [`read()`]: ../../../../std/io/trait.Write.html#tymethod.write + /// [`Duration`]: ../../../../std/time/struct.Duration.html /// /// # Examples /// @@ -389,7 +414,7 @@ impl UnixStream { /// use std::os::unix::net::UnixStream; /// use std::time::Duration; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// socket.set_write_timeout(Some(Duration::new(1, 0))).expect("Couldn't set write timeout"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] @@ -405,7 +430,7 @@ impl UnixStream { /// use std::os::unix::net::UnixStream; /// use std::time::Duration; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// socket.set_read_timeout(Some(Duration::new(1, 0))).expect("Couldn't set read timeout"); /// assert_eq!(socket.read_timeout().unwrap(), Some(Duration::new(1, 0))); /// ``` @@ -422,7 +447,7 @@ impl UnixStream { /// use std::os::unix::net::UnixStream; /// use std::time::Duration; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// socket.set_write_timeout(Some(Duration::new(1, 0))).expect("Couldn't set write timeout"); /// assert_eq!(socket.write_timeout().unwrap(), Some(Duration::new(1, 0))); /// ``` @@ -438,8 +463,8 @@ impl UnixStream { /// ```no_run /// use std::os::unix::net::UnixStream; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); - /// socket.set_nonblocking(true).expect("Couldn't set non blocking"); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); + /// socket.set_nonblocking(true).expect("Couldn't set nonblocking"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { @@ -453,7 +478,7 @@ impl UnixStream { /// ```no_run /// use std::os::unix::net::UnixStream; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// if let Ok(Some(err)) = socket.take_error() { /// println!("Got error: {:?}", err); /// } @@ -469,14 +494,15 @@ impl UnixStream { /// specified portions to immediately return with an appropriate value /// (see the documentation of [`Shutdown`]). /// - /// [`Shutdown`]: ../../std/net/enum.Shutdown.html + /// [`Shutdown`]: ../../../../std/net/enum.Shutdown.html /// /// # Examples /// /// ```no_run /// use std::os::unix::net::UnixStream; + /// use std::net::Shutdown; /// - /// let socket = match UnixStream::connect("/tmp/sock").unwrap(); + /// let socket = UnixStream::connect("/tmp/sock").unwrap(); /// socket.shutdown(Shutdown::Both).expect("shutdown function failed"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] @@ -631,7 +657,7 @@ impl UnixListener { /// is established. When established, the corersponding [`UnixStream`] and /// the remote peer's address will be returned. /// - /// [`UnixStream`]: ../../std/os/unix/net/struct.UnixStream.html + /// [`UnixStream`]: ../../../../std/os/unix/net/struct.UnixStream.html /// /// # Examples /// @@ -683,7 +709,7 @@ impl UnixListener { /// /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); /// - /// let addr = socket.local_addr().expect("Couldn't get local address"); + /// let addr = listener.local_addr().expect("Couldn't get local address"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn local_addr(&self) -> io::Result { @@ -699,7 +725,7 @@ impl UnixListener { /// /// let listener = UnixListener::bind("/path/to/the/socket").unwrap(); /// - /// socket.set_nonblocking(true).expect("Couldn't set non blocking"); + /// listener.set_nonblocking(true).expect("Couldn't set non blocking"); /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { @@ -713,8 +739,9 @@ impl UnixListener { /// ```no_run /// use std::os::unix::net::UnixListener; /// - /// let socket = match UnixListener::bind("/tmp/sock").unwrap(); - /// if let Ok(Some(err)) = socket.take_error() { + /// let listener = UnixListener::bind("/tmp/sock").unwrap(); + /// + /// if let Ok(Some(err)) = listener.take_error() { /// println!("Got error: {:?}", err); /// } /// ``` @@ -728,7 +755,7 @@ impl UnixListener { /// The iterator will never return [`None`] and will also not yield the /// peer's [`SocketAddr`] structure. /// - /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// [`None`]: ../../../../std/option/enum.Option.html#variant.None /// [`SocketAddr`]: struct.SocketAddr.html /// /// # Examples @@ -795,7 +822,7 @@ impl<'a> IntoIterator for &'a UnixListener { /// /// It will never return [`None`]. /// -/// [`None`]: ../../std/option/enum.Option.html#variant.None +/// [`None`]: ../../../../std/option/enum.Option.html#variant.None /// [`UnixListener`]: struct.UnixListener.html /// /// # Examples @@ -873,6 +900,20 @@ impl fmt::Debug for UnixDatagram { impl UnixDatagram { /// Creates a Unix datagram socket bound to the given path. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = match UnixDatagram::bind("/path/to/the/socket") { + /// Ok(sock) => sock, + /// Err(e) => { + /// println!("Couldn't bind: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn bind>(path: P) -> io::Result { fn inner(path: &Path) -> io::Result { @@ -889,6 +930,20 @@ impl UnixDatagram { } /// Creates a Unix Datagram socket which is not bound to any address. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = match UnixDatagram::unbound() { + /// Ok(sock) => sock, + /// Err(e) => { + /// println!("Couldn't unbound: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn unbound() -> io::Result { let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_DGRAM)?; @@ -898,6 +953,20 @@ impl UnixDatagram { /// Create an unnamed pair of connected sockets. /// /// Returns two `UnixDatagrams`s which are connected to each other. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let (sock1, sock2) = match UnixDatagram::pair() { + /// Ok((sock1, sock2)) => (sock1, sock2), + /// Err(e) => { + /// println!("Couldn't unbound: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn pair() -> io::Result<(UnixDatagram, UnixDatagram)> { let (i1, i2) = Socket::new_pair(libc::AF_UNIX, libc::SOCK_DGRAM)?; @@ -906,8 +975,27 @@ impl UnixDatagram { /// Connects the socket to the specified address. /// - /// The `send` method may be used to send data to the specified address. - /// `recv` and `recv_from` will only receive data from that address. + /// The [`send()`] method may be used to send data to the specified address. + /// [`recv()`] and [`recv_from()`] will only receive data from that address. + /// + /// [`send()`]: #method.send + /// [`recv()`]: #method.recv + /// [`recv_from()`]: #method.recv_from + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// match sock.connect("/path/to/the/socket") { + /// Ok(sock) => sock, + /// Err(e) => { + /// println!("Couldn't connect: {:?}", e); + /// return + /// } + /// }; + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn connect>(&self, path: P) -> io::Result<()> { fn inner(d: &UnixDatagram, path: &Path) -> io::Result<()> { @@ -924,15 +1012,35 @@ impl UnixDatagram { /// Creates a new independently owned handle to the underlying socket. /// - /// The returned `UnixListener` is a reference to the same socket that this + /// The returned `UnixDatagram` is a reference to the same socket that this /// object references. Both handles can be used to accept incoming - /// connections and options set on one listener will affect the other. + /// connections and options set on one side will affect the other. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::bind("/path/to/the/socket").unwrap(); + /// + /// let sock_copy = sock.try_clone().expect("try_clone failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn try_clone(&self) -> io::Result { self.0.duplicate().map(UnixDatagram) } /// Returns the address of this socket. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::bind("/path/to/the/socket").unwrap(); + /// + /// let addr = sock.local_addr().expect("Couldn't get local address"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn local_addr(&self) -> io::Result { SocketAddr::new(|addr, len| unsafe { libc::getsockname(*self.0.as_inner(), addr, len) }) @@ -940,7 +1048,20 @@ impl UnixDatagram { /// Returns the address of this socket's peer. /// - /// The `connect` method will connect the socket to a peer. + /// The [`connect()`] method will connect the socket to a peer. + /// + /// [`connect()`]: #method.connect + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.connect("/path/to/the/socket").unwrap(); + /// + /// let addr = sock.peer_addr().expect("Couldn't get peer address"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn peer_addr(&self) -> io::Result { SocketAddr::new(|addr, len| unsafe { libc::getpeername(*self.0.as_inner(), addr, len) }) @@ -950,6 +1071,19 @@ impl UnixDatagram { /// /// On success, returns the number of bytes read and the address from /// whence the data came. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// let mut buf = vec![0; 10]; + /// match sock.recv_from(buf.as_mut_slice()) { + /// Ok((size, sender)) => println!("received {} bytes from {:?}", size, sender), + /// Err(e) => println!("recv_from function failed: {:?}", e), + /// } + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { let mut count = 0; @@ -977,6 +1111,16 @@ impl UnixDatagram { /// Receives data from the socket. /// /// On success, returns the number of bytes read. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::bind("/path/to/the/socket").unwrap(); + /// let mut buf = vec![0; 10]; + /// sock.recv(buf.as_mut_slice()).expect("recv function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn recv(&self, buf: &mut [u8]) -> io::Result { self.0.read(buf) @@ -985,6 +1129,15 @@ impl UnixDatagram { /// Sends data on the socket to the specified address. /// /// On success, returns the number of bytes written. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.send_to(b"omelette au fromage", "/some/sock").expect("send_to function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn send_to>(&self, buf: &[u8], path: P) -> io::Result { fn inner(d: &UnixDatagram, buf: &[u8], path: &Path) -> io::Result { @@ -1009,6 +1162,16 @@ impl UnixDatagram { /// will return an error if the socket has not already been connected. /// /// On success, returns the number of bytes written. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.connect("/some/sock").expect("Couldn't connect"); + /// sock.send(b"omelette au fromage").expect("send_to function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn send(&self, buf: &[u8]) -> io::Result { self.0.write(buf) @@ -1016,9 +1179,24 @@ impl UnixDatagram { /// Sets the read timeout for the socket. /// - /// If the provided value is `None`, then `recv` and `recv_from` calls will - /// block indefinitely. It is an error to pass the zero `Duration` to this + /// If the provided value is [`None`], then [`recv()`] and [`recv_from()`] calls will + /// block indefinitely. It is an error to pass the zero [`Duration`] to this /// method. + /// + /// [`None`]: ../../../../std/option/enum.Option.html#variant.None + /// [`recv()`]: #method.recv + /// [`recv_from()`]: #method.recv_from + /// [`Duration`]: ../../../../std/time/struct.Duration.html + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// use std::time::Duration; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.set_read_timeout(Some(Duration::new(1, 0))).expect("set_read_timeout function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_read_timeout(&self, timeout: Option) -> io::Result<()> { self.0.set_timeout(timeout, libc::SO_RCVTIMEO) @@ -1026,33 +1204,92 @@ impl UnixDatagram { /// Sets the write timeout for the socket. /// - /// If the provided value is `None`, then `send` and `send_to` calls will - /// block indefinitely. It is an error to pass the zero `Duration` to this + /// If the provided value is [`None`], then [`send()`] and [`send_to()`] calls will + /// block indefinitely. It is an error to pass the zero [`Duration`] to this /// method. + /// + /// [`None`]: ../../../../std/option/enum.Option.html#variant.None + /// [`send()`]: #method.send + /// [`send_to()`]: #method.send_to + /// [`Duration`]: ../../../../std/time/struct.Duration.html + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// use std::time::Duration; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.set_write_timeout(Some(Duration::new(1, 0))) + /// .expect("set_write_timeout function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_write_timeout(&self, timeout: Option) -> io::Result<()> { self.0.set_timeout(timeout, libc::SO_SNDTIMEO) } /// Returns the read timeout of this socket. + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// use std::time::Duration; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.set_read_timeout(Some(Duration::new(1, 0))).expect("set_read_timeout function failed"); + /// assert_eq!(sock.read_timeout().unwrap(), Some(Duration::new(1, 0))); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn read_timeout(&self) -> io::Result> { self.0.timeout(libc::SO_RCVTIMEO) } /// Returns the write timeout of this socket. + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// use std::time::Duration; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.set_write_timeout(Some(Duration::new(1, 0))) + /// .expect("set_write_timeout function failed"); + /// assert_eq!(sock.write_timeout().unwrap(), Some(Duration::new(1, 0))); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn write_timeout(&self) -> io::Result> { self.0.timeout(libc::SO_SNDTIMEO) } /// Moves the socket into or out of nonblocking mode. + /// + /// # Examples + /// + /// ``` + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.set_nonblocking(true).expect("set_nonblocking function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { self.0.set_nonblocking(nonblocking) } /// Returns the value of the `SO_ERROR` option. + /// + /// # Examples + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// if let Ok(Some(err)) = sock.take_error() { + /// println!("Got error: {:?}", err); + /// } + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn take_error(&self) -> io::Result> { self.0.take_error() @@ -1062,7 +1299,17 @@ impl UnixDatagram { /// /// This function will cause all pending and future I/O calls on the /// specified portions to immediately return with an appropriate value - /// (see the documentation of `Shutdown`). + /// (see the documentation of [`Shutdown`]). + /// + /// [`Shutdown`]: ../../../../std/net/enum.Shutdown.html + /// + /// ```no_run + /// use std::os::unix::net::UnixDatagram; + /// use std::net::Shutdown; + /// + /// let sock = UnixDatagram::unbound().unwrap(); + /// sock.shutdown(Shutdown::Both).expect("shutdown function failed"); + /// ``` #[stable(feature = "unix_socket", since = "1.10.0")] pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { self.0.shutdown(how) From 0971cb18fdd2cb9150f54af10ac260ea03949f8f Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Thu, 15 Dec 2016 16:07:37 -0500 Subject: [PATCH 11/14] Document platform-specific differences for `std::process::exit`. Fixes https://github.com/rust-lang/rust/issues/35046. --- src/libstd/process.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 858537dd2de12..5a53318c49427 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -828,6 +828,12 @@ impl Child { /// this function at a known point where there are no more destructors left /// to run. /// +/// ## Platform-specific behavior +/// +/// **Unix**: On Unix-like platforms, it is unlikely that all 32 bits of `exit` +/// will be visible to a parent process inspecting the exit code. On most +/// Unix-like platforms, only the eight least-significant bits are considered. +/// /// # Examples /// /// ``` @@ -835,6 +841,17 @@ impl Child { /// /// process::exit(0); /// ``` +/// +/// Due to [platform-specific behavior], the exit code for this example will be +/// `0` on Linux, but `256` on Windows: +/// +/// ``` +/// use std::process; +/// +/// process::exit(0x0f00); +/// ``` +/// +/// [platform-specific behavior]: #platform-specific-behavior #[stable(feature = "rust1", since = "1.0.0")] pub fn exit(code: i32) -> ! { ::sys_common::cleanup(); From d409fc378ca46fca6fb0b0b986b0f11cfc62eb8f Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Mon, 12 Dec 2016 21:03:08 -0500 Subject: [PATCH 12/14] Rewrite, improve documentation for `core::hash::BuildHasherDefault`. Fixes https://github.com/rust-lang/rust/issues/31242. --- src/libcore/hash/mod.rs | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs index ac36cbaace7a8..18b465d85a12f 100644 --- a/src/libcore/hash/mod.rs +++ b/src/libcore/hash/mod.rs @@ -255,10 +255,44 @@ pub trait BuildHasher { fn build_hasher(&self) -> Self::Hasher; } -/// A structure which implements `BuildHasher` for all `Hasher` types which also -/// implement `Default`. +/// The `BuildHasherDefault` structure is used in scenarios where one has a +/// type that implements [`Hasher`] and [`Default`], but needs that type to +/// implement [`BuildHasher`]. /// -/// This struct is 0-sized and does not need construction. +/// This structure is zero-sized and does not need construction. +/// +/// # Examples +/// +/// Using `BuildHasherDefault` to specify a custom [`BuildHasher`] for +/// [`HashMap`]: +/// +/// ``` +/// use std::collections::HashMap; +/// use std::hash::{BuildHasherDefault, Hasher}; +/// +/// #[derive(Default)] +/// struct MyHasher; +/// +/// impl Hasher for MyHasher { +/// fn write(&mut self, bytes: &[u8]) { +/// // Your hashing algorithm goes here! +/// unimplemented!() +/// } +/// +/// fn finish(&self) -> u64 { +/// // Your hashing algorithm goes here! +/// unimplemented!() +/// } +/// } +/// +/// type MyBuildHasher = BuildHasherDefault; +/// +/// let hash_map = HashMap::::default(); +/// ``` +/// +/// [`BuildHasher`]: trait.BuildHasher.html +/// [`Default`]: ../default/trait.Default.html +/// [`Hasher`]: trait.Hasher.html #[stable(since = "1.7.0", feature = "build_hasher")] pub struct BuildHasherDefault(marker::PhantomData); From ca376049ca8204fa51c36dc7d4bf4991e972660c Mon Sep 17 00:00:00 2001 From: "Zack M. Davis" Date: Fri, 16 Dec 2016 17:45:59 -0800 Subject: [PATCH 13/14] tidy features: use 2-parameter form of internal try macro for open err This tiny patch merely applies @bluss's suggestion for how to get a more informative error message when the feature check can't open a file, a matter that had briefly annoyed the present author, leading to the filing of #38417. --- src/tools/tidy/src/features.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tools/tidy/src/features.rs b/src/tools/tidy/src/features.rs index 4ef07f7e4b896..ac5dff0980c08 100644 --- a/src/tools/tidy/src/features.rs +++ b/src/tools/tidy/src/features.rs @@ -67,7 +67,7 @@ pub fn check(path: &Path, bad: &mut bool) { } contents.truncate(0); - t!(t!(File::open(file)).read_to_string(&mut contents)); + t!(t!(File::open(&file), &file).read_to_string(&mut contents)); for (i, line) in contents.lines().enumerate() { let mut err = |msg: &str| { From 1e7bc907086c7eb5415f020ecde3fe7020d5b360 Mon Sep 17 00:00:00 2001 From: est31 Date: Sun, 18 Dec 2016 03:12:18 +0100 Subject: [PATCH 14/14] stage0.txt: typo fix --- src/stage0.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stage0.txt b/src/stage0.txt index 223974186b1df..96568091acbc7 100644 --- a/src/stage0.txt +++ b/src/stage0.txt @@ -2,7 +2,7 @@ # compiler itself. For the rustbuild build system, this also describes the # relevant Cargo revision that we're using. # -# Currently Rust always bootstrap from the previous stable release, and in our +# Currently Rust always bootstraps from the previous stable release, and in our # train model this means that the master branch bootstraps from beta, beta # bootstraps from current stable, and stable bootstraps from the previous stable # release.