Rust: std::os::windows missing on http://doc.rust-lang.org/nightly/std/os/

[SimonSapin]

The builders are running rustdoc on Linux, so #[cfg(windows)] is false.

Maybe the platform rustdoc in running on should not be relevant for generating documentation. Could rustdoc be run with both --cfg unix and --cfg windows?

[steveklabnik]

Could rustdoc be run with both --cfg unix and --cfg windows?

I would imagine this wouldn't work, as they have implementaitons that conflict and such.

[nwin]

This is actually not so trivial. What about things that exist on both Platforms but are different?

[klutzy]

cc #1998

[SimonSapin]

My suggested solution probably doesn’t work, but the issue remains that non-Linux things should still be documented.

[SimonSapin]

Yes, this sounds like a special case of #1998.

[steveklabnik]

I'm going to nominate this particular version, as it would be _really_ unfortunate for the official docs to only have linux docs. Maybe we can have something bespoke for 1.0 at first until the underlying bug is fixed

[nwin]

The most straightforward solution is probably to compile all docs separately and add a little pop-up box on the top to switch between Windows <-> Linux <-> Mac. I suppose one needs some more metadata to avoid that google gets confused…

[lambda]

rust-lang/rfcs#915 is a postponed RFC that proposes one possible solution.

[lambda]

This is actually not so trivial. What about things that exist on both Platforms but are different?

I think that that case should generally be avoided, shouldn't it? It would be confusing to have the same functionality available on multiple platforms, but with conflicting implementations; instead, if functionality differs meaningfully, they should probably have different names. For example, in the standard library, there are std::os::unix and std::os::windows, so even if you happened to have some operation with the same name, they'd be in different modules and so could be documented separately.

Are there current cases in the standard library or widely used crates in which items with the same name but conflicting signatures exist on the different platforms?

[nwin]

Are there current cases in the standard library or widely used crates in which items with the same name but conflicting signatures exist on the different platforms?

I was thinking of libc::types::os::common::bsd44::sockaddr_in. That struct is defined differently on Darwin and Linux (probably also Windows). I’m pretty sure there are more surprises like this lurking around.

[SimonSapin]

The most straightforward solution is probably to compile all docs separately and add a little pop-up box on the top to switch between Windows <-> Linux <-> Mac.

It would be unfortunate to duplicate the entire set of documentation for a comparatively small set of differences.

[lambda]

I was thinking of libc::types::os::common::bsd44::sockaddr_in. That struct is defined differently on Darwin and Linux (probably also Windows). I’m pretty sure there are more surprises like this lurking around.

Ah, you're right. There are a bunch of those cases in libc. I guess that means that the cfg(doc) approach probably won't work.

It would be unfortunate to duplicate the entire set of documentation for a comparatively small set of differences.

Agreed, especially since you couldn't have just those three choices, you would need to be able to switch based on any cfg option that could affect the set of methods available.

Given that it looks like it will need to support displaying different signatures for different platforms, it seems like the best you could do is list each of them, with the appropriate cfg flags listed to disambiguate which one is for which platform. That might get a little cumbersome for libc, but shouldn't affect most other code since most code should be common that doesn't depend on the platform, or platform-specific and organized in a platform-specific module; cases like libc should be more often the exception rather than the rule.

[SimonSapin]

Perhaps std::os::* modules are enough of a special case that we should generate separate docs for them specifically? Can rustdoc be instructed to document only one module and its contents?

[steveklabnik]

Rustdoc operates on crates, just like everything else. It needs to be able to compile the crate to run doc tests.

[pnkfelix]

We _should_ fix this to some degree for 1.0. There are both short-term solutions and long-term solutions.

[pnkfelix]

P-medium.

[brson]

As an immediate solution we might upload docs for all three tier-one platforms.

[KostaCitrix]

Please fix. It's really confusing to see missing/wrong documentation if working on non-linux. This is one more 'gotcha' that you need to know, so this makes it harder to start working with rust on non-linux platform.

Thank you for you consideration! :)

[steveklabnik]

I wonder if @edunham has any thoughts on this

[retep998]

We really need to upload docs for more platforms already. It is honestly quite silly that there are no docs for libstd on Windows online, especially given the sheer number of cases where people couldn't find Windows specific functionality like OsStringExt. It's such a simple thing to do, and the fact that it hasn't been done is sending a message to Windows users that Rust doesn't care about them.

[Diggsey]

I agree, IMO even just the solution used by https://docs.rs/ would be fine.

[eminence]

This could be partly solved by having local crate docs link to the local stdlib docs, instead of linking to the unix-only docs on rust-lang.org.

See the second half of #35183