API Docs: process

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/process/

Here's what needs to be done to close out this issue:

• the module docs are okay but could use elaboration.
• abort needs an example, preferably showing off its destuctor behavior. (some elaboration here, and a first PR here)
• abort should also talk about its relationship with panic!, specifically, unwinding vs aborting panics.
• abort has a bug: The [abort] function terminates the process, the []s need to be dropped.
• Child the Note shouldn't be one, and should come before the examples.
• ChildStderr should have its second sentence as not a summary, needs some newlines.
• ChildStdin has the same issue.
• ChildStdout has the same issue.
• Command is good but many of its methods could use more elaboration in their docs. See below for some details.
• ExitStatus should link to status, and its code method needs an example.
• Output should link to output.
• Stdio should link to stdio and needs expanded explanations and examples.
• exit needs some examples to show its behavior. An example of how people use this in main would be fantastic too.

With regards to Command, @frewsxcv brought up in #40983 that

• stdin, stdout, and stderr should specify what the default behavior is if they aren't explicitly called.

And @retep998 mentions

Note that the default behavior depends on whether the child process is using the console subsystem or windows subsystem. Console subsystem apps will inherit your stdout/stdin/stderr while windows subsystem apps will start with no stdout/stdin/stderr unless you explicitly assign them.

[LukasKalbertodt]

This API really could use a better documentation. To list all failure cases of several functions would be great :)

[steveklabnik]

I am happy to mentor anyone who wants to tackle this issue.

[julienXX]

I'd like to help tackle this one and learn more about the Rust process module :)

[mgattozzi]

I've had to muck around with this module a lot for my own libraries and things. I'll be glad to tackle a few of these to help document them for others.

[steveklabnik]

@julienXX @mgattozzi wonderful! Let me know if you need help in any way.

[rap2hpoutre]

Hi @steveklabnik I would like to try to tackle this issue but I need some mentor help (first time). Is adding this example for abort useless or "better than nothing"?

use std::process::abort;

fn main() {
    println!("aborting");
    abort();
}

If it's not considered useless, I could add it by creating a PR (with this code in a Examples section). Should I PR directly on master?

Side note: I don't know right how to show off its destuctor behavior

[steveklabnik]

Hey @rap2hpoutre ! Sure thing 😄

So, this example is good as a basic one, though I might add

use std::process;

fn main() {
    println!("aborting");

    process::abort();

    // execution never gets here
}

That is, two things:

1. It's considered idiomatic to import the module, and then namespace the call
2. an extra comment mentioning explicitly that the program is over at this point.

That said, after this basic example, another one would be good as well, showing this:

Side note: I don't know right how to show off its destuctor behavior

So, the key is that destruction never get run. This is in contrast with the default panic behavior, which will. Let me make another checkbox for that, I didn't even think of it.

For something like Box<T> that manages memory, this doesn't matter, as the OS will clean up the memory itself, so that's an okay but not great example.

For something that matters more, we need something with a Drop implementation that does something else. We could go one of two ways:

1. create a new structure that implements Drop that prints a message of some kind.
2. find another structure in the standard library with more interesting Drop behavior. A good example might be BufWriter:

The buffer will be written out when the writer is dropped.

The first example might be more straightforward and clear, but the latter example might be more realistic. It might even be worth it to include both, actually.... what do you think?

A PR for one, two, or three of these examples would be great. We've already talked about the first one above, but if you're interested in these more complex ones, we can go into detail about what they should look like 😄 They also don't all have to be in the same PR.

I could add it by creating a PR (with this code in a Examples section). Should I PR directly on master?

That'd be wonderful, and yes, all PRs go to master 😄

[steveklabnik]

Excellent!

[mistodon]

Done! But before I open a PR, can I make sure I'm not misunderstanding anything?

Commits for the two changes are here:
mistodon/rust@7ab20c85
mistodon/rust@6dfa45d

Also, I mention Cargo.toml in part of the description of panic=abort. Is that OK, or do we avoid mentioning cargo concepts in the std lib documentation?

[steveklabnik]

Don't worry about opening up PRs, it's actually easiest to review as a PR. WIP PRs are totally fine!

Also, I mention Cargo.toml in part of the description of panic=abort. Is that OK, or do we avoid mentioning cargo concepts in the std lib documentation?

We don't, but not due to any specific policy exactly, it's just never been directly relevant.

[steveklabnik]

(Oh, and these look good to me!)

[mistodon]

Great! I'll submit a PR just now and in future go straight ahead. Thanks for taking a look though.

[mistodon]

Think I'm going to take a look at the Stdio links/examples.

[mgattozzi]

@steveklabnik the two abort check boxes should be ticked off now that #44905 was merged

[Technius]

I'd like to help improve the module docs.

[steveklabnik]

@Technius that'd be great! Let me know if you need any help!

[mistodon]

The ExitStatus, Output, and Stdio can be checked off now, as well as the default behaviour of stdin/stdout/stderr.

The Command box can possibly also be checked off (at least it looks good to me, not sure what other detail is needed).

All that's left (I think) is module level documentation, and an explanation of how stdio works in different Windows subsystems.

[steveklabnik]

I'm giving this issue a close. Thank you to everyone who's pitched in on these docs over the last few years. If there's still improvements to do here, please open a new issue, one per thing. Thanks!