Auto merge of #43348 - kennytm:fix-24658-doc-every-platform, r=alexcrichton

Expose all OS-specific modules in libstd doc.

1. Uses the special `--cfg dox` configuration passed by rustbuild when running `rustdoc`. Changes the `#[cfg(platform)]` into `#[cfg(any(dox, platform))]` so that platform-specific API are visible to rustdoc.

2. Since platform-specific implementations often won't compile correctly on other platforms, `rustdoc` is changed to apply `everybody_loops` to the functions during documentation and doc-test harness.

3. Since platform-specific code are documented on all platforms now, it could confuse users who found a useful API but is non-portable. Also, their examples will be doc-tested, so must be excluded when not testing on the native platform. An undocumented attribute `#[doc(cfg(...))]` is introduced to serve the above purposed.

Fixes #24658 (Does _not_ fully implement #1998).

9 files changed, 96 insertions, 32 deletions

diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs
index f95fc8a1b1a..880caa2ade5 100644
--- a/src/libstd/lib.rs
+++ b/src/libstd/lib.rs
@@ -315,6 +315,7 @@
 #![feature(untagged_unions)]
 #![feature(unwind_attributes)]
 #![feature(vec_push_all)]
+#![feature(doc_cfg)]
 #![cfg_attr(test, feature(update_panic_count))]
 
 #![default_lib_allocator]
diff --git a/src/libstd/os/mod.rs b/src/libstd/os/mod.rs
index e45af867055..72eed549f62 100644
--- a/src/libstd/os/mod.rs
+++ b/src/libstd/os/mod.rs
@@ -13,26 +13,36 @@
 #![stable(feature = "os", since = "1.0.0")]
 #![allow(missing_docs, bad_style, missing_debug_implementations)]
 
-#[cfg(any(target_os = "redox", unix))]
+#[cfg(all(not(dox), any(target_os = "redox", unix)))]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use sys::ext as unix;
-#[cfg(windows)]
+#[cfg(all(not(dox), windows))]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use sys::ext as windows;
 
-#[cfg(target_os = "android")]   pub mod android;
-#[cfg(target_os = "bitrig")]    pub mod bitrig;
-#[cfg(target_os = "dragonfly")] pub mod dragonfly;
-#[cfg(target_os = "freebsd")]   pub mod freebsd;
-#[cfg(target_os = "haiku")]     pub mod haiku;
-#[cfg(target_os = "ios")]       pub mod ios;
-#[cfg(target_os = "linux")]     pub mod linux;
-#[cfg(target_os = "macos")]     pub mod macos;
-#[cfg(target_os = "nacl")]      pub mod nacl;
-#[cfg(target_os = "netbsd")]   pub mod netbsd;
-#[cfg(target_os = "openbsd")]   pub mod openbsd;
-#[cfg(target_os = "solaris")]   pub mod solaris;
-#[cfg(target_os = "emscripten")] pub mod emscripten;
-#[cfg(target_os = "fuchsia")]    pub mod fuchsia;
+#[cfg(dox)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use sys::unix_ext as unix;
+#[cfg(dox)]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub use sys::windows_ext as windows;
+
+#[cfg(any(dox, target_os = "linux"))]
+#[doc(cfg(target_os = "linux"))]
+pub mod linux;
+
+#[cfg(all(not(dox), target_os = "android"))]    pub mod android;
+#[cfg(all(not(dox), target_os = "bitrig"))]     pub mod bitrig;
+#[cfg(all(not(dox), target_os = "dragonfly"))]  pub mod dragonfly;
+#[cfg(all(not(dox), target_os = "freebsd"))]    pub mod freebsd;
+#[cfg(all(not(dox), target_os = "haiku"))]      pub mod haiku;
+#[cfg(all(not(dox), target_os = "ios"))]        pub mod ios;
+#[cfg(all(not(dox), target_os = "macos"))]      pub mod macos;
+#[cfg(all(not(dox), target_os = "nacl"))]       pub mod nacl;
+#[cfg(all(not(dox), target_os = "netbsd"))]     pub mod netbsd;
+#[cfg(all(not(dox), target_os = "openbsd"))]    pub mod openbsd;
+#[cfg(all(not(dox), target_os = "solaris"))]    pub mod solaris;
+#[cfg(all(not(dox), target_os = "emscripten"))] pub mod emscripten;
+#[cfg(all(not(dox), target_os = "fuchsia"))]    pub mod fuchsia;
 
 pub mod raw;
diff --git a/src/libstd/sys/mod.rs b/src/libstd/sys/mod.rs
index ef4dc365dbe..d91c2073a23 100644
--- a/src/libstd/sys/mod.rs
+++ b/src/libstd/sys/mod.rs
@@ -45,3 +45,33 @@ mod imp;
 #[cfg(target_os = "redox")]
 #[path = "redox/mod.rs"]
 mod imp;
+
+
+// Import essential modules from both platforms when documenting.
+
+#[cfg(all(dox, not(unix)))]
+use os::linux as platform;
+
+#[cfg(all(dox, not(any(unix, target_os = "redox"))))]
+#[path = "unix/ext/mod.rs"]
+pub mod unix_ext;
+
+#[cfg(all(dox, any(unix, target_os = "redox")))]
+pub use self::ext as unix_ext;
+
+
+#[cfg(all(dox, not(windows)))]
+#[macro_use]
+#[path = "windows/compat.rs"]
+mod compat;
+
+#[cfg(all(dox, not(windows)))]
+#[path = "windows/c.rs"]
+mod c;
+
+#[cfg(all(dox, not(windows)))]
+#[path = "windows/ext/mod.rs"]
+pub mod windows_ext;
+
+#[cfg(all(dox, windows))]
+pub use self::ext as windows_ext;
diff --git a/src/libstd/sys/redox/ext/mod.rs b/src/libstd/sys/redox/ext/mod.rs
index 0c1bf9e9557..259cda5bcb3 100644
--- a/src/libstd/sys/redox/ext/mod.rs
+++ b/src/libstd/sys/redox/ext/mod.rs
@@ -28,6 +28,7 @@
 //! ```
 
 #![stable(feature = "rust1", since = "1.0.0")]
+#![doc(cfg(target_os = "redox"))]
 
 pub mod ffi;
 pub mod fs;
diff --git a/src/libstd/sys/unix/ext/mod.rs b/src/libstd/sys/unix/ext/mod.rs
index 1be9f11b92c..67fe46cc9c7 100644
--- a/src/libstd/sys/unix/ext/mod.rs
+++ b/src/libstd/sys/unix/ext/mod.rs
@@ -28,6 +28,7 @@
 //! ```
 
 #![stable(feature = "rust1", since = "1.0.0")]
+#![doc(cfg(unix))]
 
 pub mod io;
 pub mod ffi;
diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs
index 7701ae25b41..698944ea0ba 100644
--- a/src/libstd/sys/unix/ext/net.rs
+++ b/src/libstd/sys/unix/ext/net.rs
@@ -12,8 +12,19 @@
 
 //! Unix-specific networking functionality
 
+#[cfg(unix)]
 use libc;
 
+// FIXME(#43348): Make libc adapt #[doc(cfg(...))] so we don't need these fake definitions here?
+#[cfg(not(unix))]
+mod libc {
+    pub use libc::c_int;
+    pub type socklen_t = u32;
+    pub struct sockaddr;
+    #[derive(Clone)]
+    pub struct sockaddr_un;
+}
+
 use ascii;
 use ffi::OsStr;
 use fmt;
diff --git a/src/libstd/sys/unix/mod.rs b/src/libstd/sys/unix/mod.rs
index 46e5acdf3d2..4393aedf162 100644
--- a/src/libstd/sys/unix/mod.rs
+++ b/src/libstd/sys/unix/mod.rs
@@ -13,20 +13,21 @@
 use io::{self, ErrorKind};
 use libc;
 
-#[cfg(target_os = "android")]   pub use os::android as platform;
-#[cfg(target_os = "bitrig")]    pub use os::bitrig as platform;
-#[cfg(target_os = "dragonfly")] pub use os::dragonfly as platform;
-#[cfg(target_os = "freebsd")]   pub use os::freebsd as platform;
-#[cfg(target_os = "haiku")]     pub use os::haiku as platform;
-#[cfg(target_os = "ios")]       pub use os::ios as platform;
-#[cfg(target_os = "linux")]     pub use os::linux as platform;
-#[cfg(target_os = "macos")]     pub use os::macos as platform;
-#[cfg(target_os = "nacl")]      pub use os::nacl as platform;
-#[cfg(target_os = "netbsd")]    pub use os::netbsd as platform;
-#[cfg(target_os = "openbsd")]   pub use os::openbsd as platform;
-#[cfg(target_os = "solaris")]   pub use os::solaris as platform;
-#[cfg(target_os = "emscripten")] pub use os::emscripten as platform;
-#[cfg(target_os = "fuchsia")]   pub use os::fuchsia as platform;
+#[cfg(any(dox, target_os = "linux"))] pub use os::linux as platform;
+
+#[cfg(all(not(dox), target_os = "android"))]   pub use os::android as platform;
+#[cfg(all(not(dox), target_os = "bitrig"))]    pub use os::bitrig as platform;
+#[cfg(all(not(dox), target_os = "dragonfly"))] pub use os::dragonfly as platform;
+#[cfg(all(not(dox), target_os = "freebsd"))]   pub use os::freebsd as platform;
+#[cfg(all(not(dox), target_os = "haiku"))]     pub use os::haiku as platform;
+#[cfg(all(not(dox), target_os = "ios"))]       pub use os::ios as platform;
+#[cfg(all(not(dox), target_os = "macos"))]     pub use os::macos as platform;
+#[cfg(all(not(dox), target_os = "nacl"))]      pub use os::nacl as platform;
+#[cfg(all(not(dox), target_os = "netbsd"))]    pub use os::netbsd as platform;
+#[cfg(all(not(dox), target_os = "openbsd"))]   pub use os::openbsd as platform;
+#[cfg(all(not(dox), target_os = "solaris"))]   pub use os::solaris as platform;
+#[cfg(all(not(dox), target_os = "emscripten"))] pub use os::emscripten as platform;
+#[cfg(all(not(dox), target_os = "fuchsia"))]   pub use os::fuchsia as platform;
 
 #[macro_use]
 pub mod weak;
diff --git a/src/libstd/sys/windows/c.rs b/src/libstd/sys/windows/c.rs
index 4785cefd6b4..ba54ca6ea18 100644
--- a/src/libstd/sys/windows/c.rs
+++ b/src/libstd/sys/windows/c.rs
@@ -301,7 +301,7 @@ pub const PIPE_READMODE_BYTE: DWORD = 0x00000000;
 pub const FD_SETSIZE: usize = 64;
 
 #[repr(C)]
-#[cfg(target_arch = "x86")]
+#[cfg(not(target_pointer_width = "64"))]
 pub struct WSADATA {
     pub wVersion: WORD,
     pub wHighVersion: WORD,
@@ -312,7 +312,7 @@ pub struct WSADATA {
     pub lpVendorInfo: *mut u8,
 }
 #[repr(C)]
-#[cfg(target_arch = "x86_64")]
+#[cfg(target_pointer_width = "64")]
 pub struct WSADATA {
     pub wVersion: WORD,
     pub wHighVersion: WORD,
@@ -768,6 +768,14 @@ pub struct FLOATING_SAVE_AREA {
     _Dummy: [u8; 512] // FIXME: Fill this out
 }
 
+// FIXME(#43348): This structure is used for backtrace only, and a fake
+// definition is provided here only to allow rustdoc to pass type-check. This
+// will not appear in the final documentation. This should be also defined for
+// other architectures supported by Windows such as ARM, and for historical
+// interest, maybe MIPS and PowerPC as well.
+#[cfg(all(dox, not(any(target_arch = "x86_64", target_arch = "x86"))))]
+pub enum CONTEXT {}
+
 #[repr(C)]
 pub struct SOCKADDR_STORAGE_LH {
     pub ss_family: ADDRESS_FAMILY,
diff --git a/src/libstd/sys/windows/ext/mod.rs b/src/libstd/sys/windows/ext/mod.rs
index 11b1337a8ae..4b458d293bc 100644
--- a/src/libstd/sys/windows/ext/mod.rs
+++ b/src/libstd/sys/windows/ext/mod.rs
@@ -17,6 +17,7 @@
 //! platform-agnostic idioms would not normally support.
 
 #![stable(feature = "rust1", since = "1.0.0")]
+#![doc(cfg(windows))]
 
 pub mod ffi;
 pub mod fs;