New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API Docs: os #29367

Open
steveklabnik opened this Issue Oct 26, 2015 · 11 comments

Comments

Projects
None yet
8 participants
@steveklabnik
Member

steveklabnik commented Oct 26, 2015

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

This comment has been minimized.

Member

steveklabnik commented Mar 8, 2017

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

@steveklabnik steveklabnik added the T-doc label Mar 10, 2017

@outkaj

This comment has been minimized.

outkaj commented Mar 24, 2017

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

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 24, 2017

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:

windows

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

This comment has been minimized.

Contributor

ctjhoa commented Mar 25, 2017

Can I claim the os::linux part?

@outkaj

This comment has been minimized.

outkaj commented Mar 25, 2017

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

This comment has been minimized.

Contributor

randomPoison commented Mar 25, 2017

I'd like to tackle os::windows.

ctjhoa added a commit to ctjhoa/rust that referenced this issue Mar 27, 2017

ctjhoa added a commit to ctjhoa/rust that referenced this issue Mar 28, 2017

ctjhoa added a commit to ctjhoa/rust that referenced this issue Mar 29, 2017

ctjhoa added a commit to ctjhoa/rust that referenced this issue Mar 29, 2017

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 31, 2017

Rollup merge of rust-lang#40869 - ctjhoa:master, r=steveklabnik
Improve os::linux documentation (rust-lang#29367)

Improve `os::linux` documentation according to rust-lang#29367

r? @steveklabnik

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 31, 2017

Rollup merge of rust-lang#40869 - ctjhoa:master, r=steveklabnik
Improve os::linux documentation (rust-lang#29367)

Improve `os::linux` documentation according to rust-lang#29367

r? @steveklabnik

michaelwoerister added a commit to michaelwoerister/rust that referenced this issue Apr 7, 2017

bors added a commit that referenced this issue May 19, 2017

Auto merge of #41870 - excaliburHisSheath:iss29367-windows-docs, r=fr…
…ewsxcv

Improve docs in os::windows::ffi and os::windows::fs

Part of #29367

This PR makes changes to the documentation in `os::windows::ffi` and `os::windows::fs` with the goal of fleshing them out and bringing them in line with Rust's quality standards.

r? @steveklabnik

Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue May 19, 2017

Rollup merge of rust-lang#41870 - excaliburHisSheath:iss29367-windows…
…-docs, r=frewsxcv

Improve docs in os::windows::ffi and os::windows::fs

Part of rust-lang#29367

This PR makes changes to the documentation in `os::windows::ffi` and `os::windows::fs` with the goal of fleshing them out and bringing them in line with Rust's quality standards.

r? @steveklabnik
@QuietMisdreavus

This comment has been minimized.

Member

QuietMisdreavus commented Sep 20, 2017

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

This comment has been minimized.

Member

kennytm commented Sep 21, 2017

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

@ecstatic-morse

This comment has been minimized.

Contributor

ecstatic-morse commented Apr 9, 2018

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

This comment has been minimized.

Member

steveklabnik commented Apr 10, 2018

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

This comment has been minimized.

Member

QuietMisdreavus commented Apr 10, 2018

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.

kennytm added a commit to kennytm/rust that referenced this issue Apr 24, 2018

Rollup merge of rust-lang#49829 - ecstatic-morse:os-docs, r=steveklabnik
Add doc links to `std::os` extension traits

Addresses a small subset of rust-lang#29367.

This adds documentation links to the original type for various OS-specific extension traits, and uses a common sentence for introducing such traits (which now consistently ends in a period).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment