From bde6336976f9a660fb9b14b89316ade85837fe44 Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Fri, 24 Mar 2017 23:29:23 -0400 Subject: Update `Child` docs to not have a note section In #29370 it's noted that for "the Note shouldn't be one, and should come before the examples." This commit changes the positioning of the section and removes wording that said take note in order for it to flow better with the surrounding text and it's new position. --- src/libstd/process.rs | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7a85e588662..293c8501400 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -73,6 +73,15 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// spawning process and can itself be constructed using a builder-style /// interface. /// +/// There is no implementation of [`Drop`] for child processes, +/// so if you do not ensure the `Child` has exited then it will continue to +/// run, even after the `Child` handle to the child process has gone out of +/// scope. +/// +/// Calling [`wait`][`wait`] (or other functions that wrap around it) will make +/// the parent process wait until the child has actually exited before +/// continuing. +/// /// # Examples /// /// ```should_panic @@ -89,17 +98,6 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// assert!(ecode.success()); /// ``` /// -/// # Note -/// -/// Take note that there is no implementation of [`Drop`] for child processes, -/// so if you do not ensure the `Child` has exited then it will continue to -/// run, even after the `Child` handle to the child process has gone out of -/// scope. -/// -/// Calling [`wait`][`wait`] (or other functions that wrap around it) will make -/// the parent process wait until the child has actually exited before -/// continuing. -/// /// [`Command`]: struct.Command.html /// [`Drop`]: ../../core/ops/trait.Drop.html /// [`wait`]: #method.wait -- cgit 1.4.1-3-g733a5 From 7ef1b39b2525dc5475f86b6dc27aa60fe5b3fdca Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Sat, 25 Mar 2017 16:16:50 -0400 Subject: Remove extra wait from Child docs --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 293c8501400..edcf206501a 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -78,7 +78,7 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// run, even after the `Child` handle to the child process has gone out of /// scope. /// -/// Calling [`wait`][`wait`] (or other functions that wrap around it) will make +/// Calling [`wait`] (or other functions that wrap around it) will make /// the parent process wait until the child has actually exited before /// continuing. /// -- cgit 1.4.1-3-g733a5 From 1d59c67942ea682d0de4bb847d6da38d6417e07d Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Sat, 25 Mar 2017 17:19:36 -0400 Subject: Update ChildStderr docs to be clearer Before the docs only had a line about where it was found and that it was a handle to stderr. This commit changes it so that the summary second line is removed and that it's a bit clearer about what can be done with it. Part of \#29370 --- src/libstd/process.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7a85e588662..265228281f8 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -233,8 +233,9 @@ impl fmt::Debug for ChildStdout { } } -/// A handle to a child process's stderr. This struct is used in the [`stderr`] -/// field on [`Child`]. +/// A handle to a child process's stderr. It can be used to +/// read any errors that the child process has output while +/// running. /// /// [`Child`]: struct.Child.html /// [`stderr`]: struct.Child.html#structfield.stderr -- cgit 1.4.1-3-g733a5 From 022bae8a4a9254fbdb4217e86927809f0ad996d6 Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 29 Mar 2017 15:59:22 +0200 Subject: Add example to std::process::abort --- src/libstd/process.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index d46cf7a26da..32b52d1f77a 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1056,6 +1056,19 @@ pub fn exit(code: i32) -> ! { /// will be run. If a clean shutdown is needed it is recommended to only call /// this function at a known point where there are no more destructors left /// to run. +/// +/// # Examples +/// ``` +/// use std::process; +/// +/// fn main() { +/// println!("aborting"); +/// +/// process::abort(); +/// +/// // execution never gets here +/// } +/// ``` #[stable(feature = "process_abort", since = "1.17.0")] pub fn abort() -> ! { unsafe { ::sys::abort_internal() }; -- cgit 1.4.1-3-g733a5 From 3ac27c3e54f3f5477ea907246c872523f14ef6df Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 29 Mar 2017 16:19:23 +0200 Subject: adding /// --- src/libstd/process.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 32b52d1f77a..83d34f71a70 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1058,6 +1058,7 @@ pub fn exit(code: i32) -> ! { /// to run. /// /// # Examples +/// /// ``` /// use std::process; /// -- cgit 1.4.1-3-g733a5 From 5a7e9ad64a160c9ebfb35969f2bdd1065bc154bb Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 29 Mar 2017 16:30:39 +0200 Subject: Removing trailing spaces --- src/libstd/process.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 83d34f71a70..a86dba97f78 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1061,12 +1061,12 @@ pub fn exit(code: i32) -> ! { /// /// ``` /// use std::process; -/// +/// /// fn main() { /// println!("aborting"); -/// +/// /// process::abort(); -/// +/// /// // execution never gets here /// } /// ``` -- cgit 1.4.1-3-g733a5 From 1be84cee75687856c0032ad0fd5ea96945c067b7 Mon Sep 17 00:00:00 2001 From: raph Date: Thu, 30 Mar 2017 09:55:44 +0200 Subject: Update process.rs --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index a86dba97f78..7f1a00c707c 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1059,7 +1059,7 @@ pub fn exit(code: i32) -> ! { /// /// # Examples /// -/// ``` +/// ```no_run /// use std::process; /// /// fn main() { -- cgit 1.4.1-3-g733a5 From c7f2dbef90231eab0b0f2032854823d192a964eb Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Tue, 4 Apr 2017 16:23:52 -0400 Subject: Change docs to follow review requests --- src/libstd/process.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 265228281f8..123138daeea 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -233,9 +233,9 @@ impl fmt::Debug for ChildStdout { } } -/// A handle to a child process's stderr. It can be used to -/// read any errors that the child process has output while -/// running. +/// A handle to a child process's stderr. +/// +/// This struct is used in the [`stderr`] field on [`Child`]. /// /// [`Child`]: struct.Child.html /// [`stderr`]: struct.Child.html#structfield.stderr -- cgit 1.4.1-3-g733a5 From 4e1147f3406bcd368c50c89242bbba6a6fec5127 Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 5 Apr 2017 20:41:43 +0200 Subject: Add example to std::process::abort This is a second (2/3?) step in order to complete this issue: https://github.com/rust-lang/rust/issues/29370 I submitted this PR with the help of @steveklabnik again. Thanks to him! More info here: https://github.com/rust-lang/rust/issues/29370#issuecomment-290653877 --- src/libstd/process.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7f1a00c707c..95e625888cc 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1070,6 +1070,28 @@ pub fn exit(code: i32) -> ! { /// // execution never gets here /// } /// ``` +/// +/// The abort function terminates the process, so the destructor will not get +/// run on the example below: +/// +/// ```no_run +/// use std::process; +/// +/// struct HasDrop; +/// +/// impl Drop for HasDrop { +/// fn drop(&mut self) { +/// println!("This will never be printed!"); +/// } +/// } +/// +/// fn main() { +/// let _x = HasDrop; +/// process::abort(); +/// // the destructor implemented for HasDrop will never get run +/// } +/// ``` +/// #[stable(feature = "process_abort", since = "1.17.0")] pub fn abort() -> ! { unsafe { ::sys::abort_internal() }; -- cgit 1.4.1-3-g733a5 From 16c77d7da1d1707a90d94d9eb77e0752f974a0db Mon Sep 17 00:00:00 2001 From: raph Date: Thu, 6 Apr 2017 10:17:32 +0200 Subject: Update process.rs --- src/libstd/process.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 95e625888cc..8cfd8fcd8c6 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1071,8 +1071,8 @@ pub fn exit(code: i32) -> ! { /// } /// ``` /// -/// The abort function terminates the process, so the destructor will not get -/// run on the example below: +/// The [`abort`] function terminates the process, so the destructor will not +/// get run on the example below: /// /// ```no_run /// use std::process; @@ -1091,7 +1091,6 @@ pub fn exit(code: i32) -> ! { /// // the destructor implemented for HasDrop will never get run /// } /// ``` -/// #[stable(feature = "process_abort", since = "1.17.0")] pub fn abort() -> ! { unsafe { ::sys::abort_internal() }; -- cgit 1.4.1-3-g733a5 From df383b95476d59c26e822bcda69d3255da61622c Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Wed, 19 Apr 2017 14:00:50 -0400 Subject: Fix link for wait --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index edcf206501a..9d7f87f06c3 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -78,7 +78,7 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// run, even after the `Child` handle to the child process has gone out of /// scope. /// -/// Calling [`wait`] (or other functions that wrap around it) will make +/// Calling [`wait`](#method.wait) (or other functions that wrap around it) will make /// the parent process wait until the child has actually exited before /// continuing. /// -- cgit 1.4.1-3-g733a5 From 7423966714aba0bedafee2d7c957363a25f2d849 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Mon, 1 May 2017 20:38:59 -0400 Subject: Fix incorrect hex value in doc comment example. --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/process.rs') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 4ec9076de61..23ebeb4b8e3 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1035,7 +1035,7 @@ impl Child { /// ```no_run /// use std::process; /// -/// process::exit(0x0f00); +/// process::exit(0x0100); /// ``` /// /// [platform-specific behavior]: #platform-specific-behavior -- 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/process.rs') 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