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.

[QuietMisdreavus]

Note that thanks to #43348, the platform docs for Linux, Unix, and Windows are all shown on https://doc.rust-lang.org/nightly/std/os/. (As this change rides the trains, it'll make its way to the stable docs - i assume it'll come with the next stable release.) So a proper fix for this would need to take at least those platform modules into account before calling this good. Adding macOS to the list would be helpful, just to get the major desktop platforms accounted for. I would consider farther improvements for system-specific modules beyond that (iOS, Android, *BSD, etc) to be "bonus points" on this specific effort.

This will likely take several PRs, as various people who know different platforms elaborate on the behavior they know about.

[kennytm]

The difference between std::os::{linux, macos, freebsd, …} is just the fs::MetadataExt trait though, there isn't much to document.

[ecstatic-morse]

I'm writing a module level description for std::os which explains in detail the point of the module as well as mentioning why only windows, unix, and linux are shown in the docs hosted on the website.

However, the part of this comment talking about using rustup doc to view the platform-specific modules for the local platform seems to be out of date. Running it on my Linux box still shows the windows module. Is there still a way to generate docs for the local platform beyond building from source?

[steveklabnik]

However, the part of this comment talking about using rustup doc to view the platform-specific modules for the local platform seems to be out of date. Running it on my Linux box still shows the windows module. Is there still a way to generate docs for the local platform beyond building from source?

@QuietMisdreavus ? As far as I know, the answer now is "no".

[QuietMisdreavus]

Unfortunately, even building from source yourself will still only show Linux, Unix, and Windows in the documentation, regardless of what target you're building for. In the source for std::os it has a cfg_if! block that will bypass every other module while the docs are being created. There was probably a sound reason it completely ignores the other target docs, but that's the current culprit. I would prefer it if the other targets were shown on their respective target builds (or even better, all the time) but there have been headaches in the past trying to integrate doc(cfg) very broadly. If you want to show the OS docs, that's where i'd start.

[Dylan-DPC-zz]

Closing this as the docs have been updated :)