API Docs: thread

[steveklabnik]

Part of #29329

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

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

• the module docs are written a while ago, and contain some questionableish advice. It's not actually bad, it's just not the way I'd orient all of this. A particularly enthusiastic contributor could toss this out and re-write it from scratch. If the rest of this work gets done, we can close the ticket without doing this, but it would be nice.
• Builder's docs are... okay. Just very uninspired.
• JoinHandle doesn't go into enough detail, and should show off, for example, the detach behavior.
• LocalKey could use some links and general cleanup.
• Thread has very little and very boring docs.
• panicking could use some more advice on when to use this.
• park should have its module documentation inlined here, and cleaned up.
• park_timeout could use links to park
• spawn needs a lot more docs generally. It's the main interface to this module!
• yield_now doesn't explain any of the "why".
• Result should at least show off the "use std::thread; thread::Result" pattern, like all module-specific Result types.

[steveklabnik]

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

[zimurgh]

I would be interested in taking on the documentation improvement of Builder as a starter. I'd take on more, but no need to get ahead of myself.

[steveklabnik]

@OldManMike awesome! Please let me know if you need anything.

[ghost]

I am not (by any means) an expert on this topic but I'd love to help on this one, as @steveklabnik says: writting docs is the best way to learn something

[ghost]

I believe I will be taking the joinHandle and Thead docs

[rap2hpoutre]

I would like to tackle this issue too and add an example on Result. Feel free to stop me if you are already working on it! (but it seems nobody took it right now)

[rap2hpoutre]

Ok so I still need some mentoring! Here is a (working) example I quickly wrote for std::thread::Result.

use std::thread;

fn main() {
    let child = thread::spawn(move || panic!("Oups"));

    let res: thread::Result<()> = child.join();

    match res {
        Ok(_) => println!("this is fine"),
        Err(_) => println!("thread panicked"),
    }
}

I think (but not sure) this example could help because type is explicit, so the user know what he can do with this std::thread::Result.

@steveklabnik asked:

Result should at least show off the "use std::thread; thread::Result" pattern, like all module-specific Result types.

But I'm not sure to understand what does "use std::thread; thread::Result" means. I read an other example in std on io::Result: https://doc.rust-lang.org/std/io/type.Result.html but it seems different, I preferred wrote something more specific to threads.

Anyway, I'm not sure my example follows best practices. And I'm not sure it's useful. So, once again @steveklabnik please help! :)

[steveklabnik]

But I'm not sure to understand what does "use std::thread; thread::Result" means. I read an other example in std on io::Result: https://doc.rust-lang.org/std/io/type.Result.html but it seems different, I preferred wrote something more specific to threads.

It's what you wrote, specifically

use std::thread;

let res: thread::Result<()> ...

that is, you use this style instead of use std::thread::Result; which would be more conventional generally speaking. The reason why is so you don't shadow std::result::Result from the prelude.

Anyway, I'm not sure my example follows best practices. And I'm not sure it's useful. So, once again @steveklabnik please help! :)

I think this example is okay, but we might be able to make it better! What about a function that does the spawn and join, and returns the result? then, you wouldn't be adding the extra type for no reason, as the function signature would use it. This is similar to how the Write trait has methods that return their Results.

The question is what that function should do...

[rap2hpoutre]

What about a function that does the spawn and join, and returns the result?

Okay, I think you mean:

use std::thread;

fn spawn_and_join() -> thread::Result<()> {
    let child = thread::spawn(move || panic!("Oups"));
    child.join()
}

fn main() {
    match spawn_and_join() {
        Ok(_) => println!("this is fine"),
        Err(_) => println!("thread panicked"),
    }
}

But...

The question is what that function should do...

From there I'm a bit lost: my example has still no sense (what's that spawn_and_join function and why?), but I don't know how to create something with sense in a few lines. Maybe I should call something that could panic? Something like:

fn open_file_in_thread() -> thread::Result<()> {
    let child = thread::spawn(move || {
        File::open("foo.txt").unwrap();
        // etc.
    });
    child.join()
}

But it's a "not real" example either. Should I give up?

EDIT: Maybe a file copy in a thread could be more realistic: fs::copy("foo.txt", "bar.txt") with a copy_in_thread function

use std::thread;
use std::fs;

fn copy_in_thread() -> thread::Result<()> {
    thread::spawn(move || { fs::copy("foo.txt", "bar.txt").unwrap(); }).join()
}

fn main() {
    match copy_in_thread() {
        Ok(_) => println!("this is fine"),
        Err(_) => println!("thread panicked"),
    }
}

[gamazeps]

@steveklabnik Hey ! I'm a bit rusty (haven't rusted in a year or so), so I'm looking to get back to it by helping with the docs, which item still need documentation in the list ?

Cheers

[steveklabnik]

@gamazeps wonderful! Everything except the last one is still open, and that's because there's a PR open, but not merged, hence no checkmark.

[gamazeps]

@steveklabnik Ok, sign me in for:

• Thread has very little and very boring docs.
• panicking could use some more advice on when to use this.
• park should have its module documentation inlined here, and cleaned up.
• park_timeout could use links to park
• spawn needs a lot more docs generally. It's the main interface to this module!

Should be done by wednesdy in the worst case scenario :)

[steveklabnik]

@gamazeps thank you so much! ❤️

[seanprashad]

Hi @steveklabnik! I'd LOVE to help bring this across the finish line but with the last documentation issue for the module docs. I'd greatly appreciate some guidance with where to start if it's possible 🙂

[steveklabnik]

Hey @seanprashad that'd be amazing!

One option is

A particularly enthusiastic contributor could toss this out and re-write it from scratch.

Which would be a bunch of work but might be the way to go.

Basically, I don't think the docs are organized well; they're kind of just a random collection of thoughts. So I think the first task is, how do we want to organize these docs? Generally, good module docs show an overview of the module conceptually, and then highlight key APIs. Maybe we can start there?

[steveklabnik]

Quoting myself above:

If the rest of this work gets done, we can close the ticket without doing this, but it would be nice.

We haven't come up with a good plan for the module docs, and so I'm going to close this ticket. If anyone has specific thoughts about improving them, please open a new ticket with details! Thanks.