From 08514b4376eda86f2c05d91334333ebf8caad064 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Tue, 25 Apr 2017 17:22:34 -0500 Subject: rewrote the thread struct docs --- src/libstd/thread/mod.rs | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index e37cc7e963e..98452a396aa 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -713,22 +713,27 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread. +/// A handle to a thread, its just an abstract reference and as such +/// it can be used to identify a thread (by name, for example). In most +/// usage cases, this struct is not used directly. /// /// # Examples /// /// ``` /// use std::thread; /// -/// let handler = thread::Builder::new() -/// .name("foo".into()) +/// for i in 0..5 { +/// let thread_name = format!("thread_{}", i); +/// thread::Builder::new() +/// .name(thread_name) // Now you can identify which thread panicked +/// // thanks to the handle's name /// .spawn(|| { -/// let thread = thread::current(); -/// println!("thread name: {}", thread.name().unwrap()); +/// if i == 3 { +/// panic!("I'm scared!!!"); +/// } /// }) /// .unwrap(); -/// -/// handler.join().unwrap(); +/// } /// ``` pub struct Thread { inner: Arc, -- cgit 1.4.1-3-g733a5 From bdb6bb9684e5cc874d69d6cd65be3d9fb1e64401 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Wed, 26 Apr 2017 00:57:59 -0500 Subject: added move --- src/libstd/thread/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 98452a396aa..aa7ef2da0ae 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -727,7 +727,7 @@ struct Inner { /// thread::Builder::new() /// .name(thread_name) // Now you can identify which thread panicked /// // thanks to the handle's name -/// .spawn(|| { +/// .spawn(move || { /// if i == 3 { /// panic!("I'm scared!!!"); /// } -- cgit 1.4.1-3-g733a5 From cf521211a13ccb7e8ea25af97d0efc3abe6d9070 Mon Sep 17 00:00:00 2001 From: Christian Poveda Date: Wed, 26 Apr 2017 11:54:17 -0500 Subject: restructured docs for thread and added links --- src/libstd/thread/mod.rs | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index aa7ef2da0ae..4e49c485f10 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -713,28 +713,34 @@ struct Inner { #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread, its just an abstract reference and as such -/// it can be used to identify a thread (by name, for example). In most -/// usage cases, this struct is not used directly. +/// A handle to a thread. +/// +/// You can use it to identify a thread (by name, for example). Most of the +/// time, there is no need to directly create a `Thread` struct using the +/// constructor, instead you should use a function like `spawn` to create +/// new threads, see the docs of [`Builder`] and [`spawn`] for more. /// /// # Examples /// /// ``` -/// use std::thread; +/// use std::thread::Builder; /// /// for i in 0..5 { /// let thread_name = format!("thread_{}", i); -/// thread::Builder::new() -/// .name(thread_name) // Now you can identify which thread panicked -/// // thanks to the handle's name -/// .spawn(move || { -/// if i == 3 { -/// panic!("I'm scared!!!"); -/// } -/// }) -/// .unwrap(); +/// Builder::new() +/// .name(thread_name) // Now you can identify which thread panicked +/// // thanks to the handle's name +/// .spawn(move || { +/// if i == 3 { +/// panic!("I'm scared!!!"); +/// } +/// }) +/// .unwrap(); /// } /// ``` +/// [`Builder`]: ../../std/thread/struct.Builder.html +/// [`spawn`]: ../../std/thread/fn.spawn.html + pub struct Thread { inner: Arc, } -- cgit 1.4.1-3-g733a5 From aa10fce346e1a19f4badb22a6bb8a240c1fd53db Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 2 May 2017 23:55:40 -0400 Subject: Update Duration::from_secs doc example to show underlying values. --- src/libstd/time/duration.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/time/duration.rs b/src/libstd/time/duration.rs index af7eaeb3106..bd8c1fac2db 100644 --- a/src/libstd/time/duration.rs +++ b/src/libstd/time/duration.rs @@ -84,7 +84,10 @@ impl Duration { /// ``` /// use std::time::Duration; /// - /// let five_seconds = Duration::from_secs(5); + /// let duration = Duration::from_secs(5); + /// + /// assert_eq!(5, duration.as_secs()); + /// assert_eq!(0, duration.subsec_nanos()); /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] -- cgit 1.4.1-3-g733a5 From ee8ad8eb2e38092096d241f5c2a9df369029497c Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 2 May 2017 23:56:29 -0400 Subject: Update Duration::from_millis doc example to show underlying values. --- src/libstd/time/duration.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/time/duration.rs b/src/libstd/time/duration.rs index bd8c1fac2db..268ce733fa3 100644 --- a/src/libstd/time/duration.rs +++ b/src/libstd/time/duration.rs @@ -102,7 +102,10 @@ impl Duration { /// ``` /// use std::time::Duration; /// - /// let five_seconds = Duration::from_millis(5000); + /// let duration = Duration::from_millis(2569); + /// + /// assert_eq!(2, duration.as_secs()); + /// assert_eq!(569000000, duration.subsec_nanos()); /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] -- cgit 1.4.1-3-g733a5 From bdd8e7ffe6cb1cdf100b9ca071e826f153371245 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 2 May 2017 23:58:39 -0400 Subject: Update Duration::as_secs doc example to demonstrate truncation. --- src/libstd/time/duration.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/time/duration.rs b/src/libstd/time/duration.rs index 268ce733fa3..4f8f9c36ec7 100644 --- a/src/libstd/time/duration.rs +++ b/src/libstd/time/duration.rs @@ -125,8 +125,8 @@ impl Duration { /// ``` /// use std::time::Duration; /// - /// let five_seconds = Duration::new(5, 0); - /// assert_eq!(five_seconds.as_secs(), 5); + /// let duration = Duration::new(5, 730023852); + /// assert_eq!(duration.as_secs(), 5); /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] -- cgit 1.4.1-3-g733a5 From a3e8f3622f62022d98c2df1f096f4ef88efb6386 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Wed, 3 May 2017 00:04:59 -0400 Subject: Add doc example for how to determine total number of secs in Duration. --- src/libstd/time/duration.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/time/duration.rs b/src/libstd/time/duration.rs index 4f8f9c36ec7..55766ba3fed 100644 --- a/src/libstd/time/duration.rs +++ b/src/libstd/time/duration.rs @@ -128,6 +128,21 @@ impl Duration { /// let duration = Duration::new(5, 730023852); /// assert_eq!(duration.as_secs(), 5); /// ``` + /// + /// To determine the total number of seconds represented by the `Duration`, + /// use `as_secs` in combination with [`subsec_nanos`]: + /// + /// ``` + /// use std::time::Duration; + /// + /// let duration = Duration::new(5, 730023852); + /// + /// assert_eq!(5.730023852, + /// duration.as_secs() as f64 + /// + duration.subsec_nanos() as f64 * 1e-9); + /// ``` + /// + /// [`subsec_nanos`]: #method.subsec_nanos #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn as_secs(&self) -> u64 { self.secs } -- cgit 1.4.1-3-g733a5 From 28a4f57dd0161d7602aed0005ebeddaa5e646367 Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Wed, 3 May 2017 01:13:18 -0400 Subject: Update ChildStdin/ChildStdout docs to be clearer --- src/libstd/process.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 23ebeb4b8e3..3896fc20a2d 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -148,8 +148,9 @@ impl fmt::Debug for Child { } } -/// A handle to a child process's stdin. This struct is used in the [`stdin`] -/// field on [`Child`]. +/// A handle to a child process's stdin. +/// +/// This struct is used in the [`stdin`] field on [`Child`]. /// /// [`Child`]: struct.Child.html /// [`stdin`]: struct.Child.html#structfield.stdin @@ -190,8 +191,9 @@ impl fmt::Debug for ChildStdin { } } -/// A handle to a child process's stdout. This struct is used in the [`stdout`] -/// field on [`Child`]. +/// A handle to a child process's stdout. +/// +/// This struct is used in the [`stdout`] field on [`Child`]. /// /// [`Child`]: struct.Child.html /// [`stdout`]: struct.Child.html#structfield.stdout -- cgit 1.4.1-3-g733a5