From 24334a03a3e3e6137b0810ebc14ac37e37a53349 Mon Sep 17 00:00:00 2001 From: Esteban Küber Date: Tue, 20 Dec 2016 17:09:36 -0800 Subject: Docs: Explain why/when `.lines()` returns an error --- src/libstd/io/mod.rs | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index b07da0dc268..6ba614fa2e3 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -1425,6 +1425,12 @@ pub trait BufRead: Read { /// println!("{}", line.unwrap()); /// } /// ``` + /// + /// # Errors + /// + /// Each line of the iterator has the same error semantics as [`BufRead::read_line()`]. + /// + /// [`BufRead::read_line()`]: trait.BufRead.html#method.read_line #[stable(feature = "rust1", since = "1.0.0")] fn lines(self) -> Lines where Self: Sized { Lines { buf: self } -- cgit 1.4.1-3-g733a5 From 99529825e8765a1241c569495bca83218fc5e498 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 21 Dec 2016 18:05:11 +0100 Subject: Add missing examples in some thread functions --- src/libstd/thread/mod.rs | 51 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 43 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2a3fb5ec43f..d3949743bca 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -318,20 +318,38 @@ impl Builder { // Free functions //////////////////////////////////////////////////////////////////////////////// -/// Spawns a new thread, returning a `JoinHandle` for it. +/// Spawns a new thread, returning a [`JoinHandle`] for it. /// /// The join handle will implicitly *detach* the child thread upon being /// dropped. In this case, the child thread may outlive the parent (unless /// the parent thread is the main thread; the whole process is terminated when -/// the main thread finishes.) Additionally, the join handle provides a `join` +/// the main thread finishes). Additionally, the join handle provides a [`join`] /// method that can be used to join the child thread. If the child thread -/// panics, `join` will return an `Err` containing the argument given to -/// `panic`. +/// panics, [`join`] will return an [`Err`] containing the argument given to +/// [`panic`]. /// /// # Panics /// -/// Panics if the OS fails to create a thread; use `Builder::spawn` +/// Panics if the OS fails to create a thread; use [`Builder::spawn`] /// to recover from such errors. +/// +/// [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html +/// [`join`]: ../../std/thread/struct.JoinHandle.html#method.join +/// [`Err`]: ../../std/result/enum.Result.html#variant.Err +/// [`panic!`]: ../../std/macro.panic.html +/// [`Builder::spawn`]: ../../std/thread/struct.Builder.html#method.spawn +/// +/// # Examples +/// +/// ``` +/// use std::thread; +/// +/// let handler = thread::spawn(|| { +/// // thread code +/// }); +/// +/// handler.join().unwrap(); +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn spawn(f: F) -> JoinHandle where F: FnOnce() -> T, F: Send + 'static, T: Send + 'static @@ -341,7 +359,7 @@ pub fn spawn(f: F) -> JoinHandle where /// Gets a handle to the thread that invokes it. /// -/// #Examples +/// # Examples /// /// Getting a handle to the current thread with `thread::current()`: /// @@ -366,6 +384,14 @@ pub fn current() -> Thread { } /// Cooperatively gives up a timeslice to the OS scheduler. +/// +/// # Examples +/// +/// ``` +/// use std::thread; +/// +/// thread::yield_now(); +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn yield_now() { imp::Thread::yield_now() @@ -375,7 +401,7 @@ pub fn yield_now() { /// /// # Examples /// -/// ```rust,should_panic +/// ```should_panic /// use std::thread; /// /// struct SomeStruct; @@ -413,6 +439,15 @@ pub fn panicking() -> bool { /// specifics or platform-dependent functionality. Note that on unix platforms /// this function will not return early due to a signal being received or a /// spurious wakeup. +/// +/// # Examples +/// +/// ```no_run +/// use std::thread; +/// +/// // Let's sleep for 2 seconds: +/// thread::sleep_ms(2000); +/// ``` #[stable(feature = "rust1", since = "1.0.0")] #[rustc_deprecated(since = "1.6.0", reason = "replaced by `std::thread::sleep`")] pub fn sleep_ms(ms: u32) { @@ -433,7 +468,7 @@ pub fn sleep_ms(ms: u32) { /// /// # Examples /// -/// ```rust,no_run +/// ```no_run /// use std::{thread, time}; /// /// let ten_millis = time::Duration::from_millis(10); -- cgit 1.4.1-3-g733a5 From 88af5bf5ecfebe1683ab449213d218de7871cc92 Mon Sep 17 00:00:00 2001 From: Jason Campbell Date: Wed, 21 Dec 2016 13:28:08 -0800 Subject: Removes magenta build warning. Small bug fix to remove an unused type in the magenta process code that causes build failures for magenta's rustc. --- src/libstd/sys/unix/process/magenta.rs | 1 - 1 file changed, 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/unix/process/magenta.rs b/src/libstd/sys/unix/process/magenta.rs index 319fbce35cd..2bb005be4ec 100644 --- a/src/libstd/sys/unix/process/magenta.rs +++ b/src/libstd/sys/unix/process/magenta.rs @@ -23,7 +23,6 @@ pub type mx_rights_t = u32; pub type mx_status_t = i32; pub type mx_size_t = usize; -pub type mx_ssize_t = isize; pub const MX_HANDLE_INVALID: mx_handle_t = 0; -- cgit 1.4.1-3-g733a5 From 00645e85043b9830118d4c9aecb59cc2c041b437 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 23 Dec 2016 11:25:11 +0100 Subject: Add JoinHandle missing examples --- src/libstd/thread/mod.rs | 46 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 6 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 2a3fb5ec43f..0ba009e5867 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -749,7 +749,7 @@ impl JoinInner { /// /// A `JoinHandle` *detaches* the child thread when it is dropped. /// -/// Due to platform restrictions, it is not possible to `Clone` this +/// Due to platform restrictions, it is not possible to [`Clone`] this /// handle: the ability to join a child thread is a uniquely-owned /// permission. /// @@ -760,7 +760,7 @@ impl JoinInner { /// /// Creation from [`thread::spawn`]: /// -/// ```rust +/// ``` /// use std::thread; /// /// let join_handle: thread::JoinHandle<_> = thread::spawn(|| { @@ -770,7 +770,7 @@ impl JoinInner { /// /// Creation from [`thread::Builder::spawn`]: /// -/// ```rust +/// ``` /// use std::thread; /// /// let builder = thread::Builder::new(); @@ -780,13 +780,31 @@ impl JoinInner { /// }).unwrap(); /// ``` /// +/// [`Clone`]: ../../std/clone/trait.Clone.html /// [`thread::spawn`]: fn.spawn.html /// [`thread::Builder::spawn`]: struct.Builder.html#method.spawn #[stable(feature = "rust1", since = "1.0.0")] pub struct JoinHandle(JoinInner); impl JoinHandle { - /// Extracts a handle to the underlying thread + /// Extracts a handle to the underlying thread. + /// + /// # Examples + /// + /// ``` + /// #![feature(thread_id)] + /// + /// use std::thread; + /// + /// let builder = thread::Builder::new(); + /// + /// let join_handle: thread::JoinHandle<_> = builder.spawn(|| { + /// // some work here + /// }).unwrap(); + /// + /// let thread = join_handle.thread(); + /// println!("thread id: {:?}", thread.id()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn thread(&self) -> &Thread { &self.0.thread @@ -794,8 +812,24 @@ impl JoinHandle { /// Waits for the associated thread to finish. /// - /// If the child thread panics, `Err` is returned with the parameter given - /// to `panic`. + /// If the child thread panics, [`Err`] is returned with the parameter given + /// to [`panic`]. + /// + /// [`Err`]: ../../std/result/enum.Result.html#variant.Err + /// [`panic!`]: ../../std/macro.panic.html + /// + /// # Examples + /// + /// ``` + /// use std::thread; + /// + /// let builder = thread::Builder::new(); + /// + /// let join_handle: thread::JoinHandle<_> = builder.spawn(|| { + /// // some work here + /// }).unwrap(); + /// join_handle.join().expect("Couldn't join on the associated thread"); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn join(mut self) -> Result { self.0.join() -- cgit 1.4.1-3-g733a5