API Docs: os

[steveklabnik]

Part of #29329

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

This will be tough, as there's a lot of platforms...

This comment contains a checklist of what needs to be done for this issue.

[steveklabnik]

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

[outkaj]

I am curious to learn more about the steps needed to resolve this issue. Thanks!

[steveklabnik]

Hey @outkaj !

So, for some context, I opened up one of these issues for every module in the standard library. So in some sense, this issue represents "read everything over and see if it's good enough yet." So it's very open-ended.

Looking at it now, some things that should be done to close this ticket:

• the module docs should have more than a partial sentence.

Generally these have an overview of the functionality in the module. This one is special though; for example, compare what that page looks like to this screenshot on my local machine:

We build the docs on linux, so we only have linux docs on the website, but you get the ones locally for the platform you're on. This is a great thing to mention on this page, as well as that rustup doc (and rustup component add rust-docs) is a good way to get the ones for your platform.

• os::raw has similar needs; no real API docs, no docs on the types. Something that'd be good to put here is to compare this module vs libc's types, it's never been clear to me when to use this module vs libc. @rust-lang/libs would know that answer, though!

• os::linux really only has one submodule of note, and that one only has one trait, MetadataExt. It needs a bunch of docs.

• os::unix has docs which are already out of date! "For now, this module is limited to extracting file descriptors, but its functionality will grow over time." is wrong, it seems, look at those modules at the bottom! In general we try not to use language like this, specifically because it gets out of date. Furthermore, "Experimental extensions to std for Unix platforms." is awkward, because they're not necessarily experimental; a lot of this stuff is stable. Within this module, there's a ton of stuff, and it all has the same problems as the above.

• os::windows has the same language problems: "Experimental extensions to std for Windows. / For now, this module is limited to extracting handles, file descriptors, and sockets, but its functionality will grow over time." It also has a bunch of sub-modules for other platforms.

I don't have access to a mac to easily generate mac instructions, and this is getting long, so I wont' dig into the source, but I'm assuming it has the same kinds of issues.

Whew! That's a lot. As I said in the first issue, this one is big. If you're interested in chipping in here, please send in PRs of any size; I actually prefer a large number of small PRs to one huge PR. And helping with part of this is just as good as tackling all of it; this module specifically is a huge job with a lot of details, so I imagine we'll be chipping away at it over time.

And don't hesitate to ping me here, on IRC, or over email if you (or anyone else working on stuff) needs any help at all!

Thanks 😄

[ctjhoa]

Can I claim the os::linux part?

[outkaj]

This is very helpful - thank you!

I can take a look at expanding the description in the module docs, as well as start looking into os:: unix, and will definitely reach out with questions.

I don't have access to a Windows or Mac system at the moment, so unfortunately can't contribute in that regard.

[randomPoison]

I'd like to tackle os::windows.