From 62a810b4b8ed8a8dccd67041ecbadcbb77cbe437 Mon Sep 17 00:00:00 2001 From: Alan Somers Date: Wed, 30 Jan 2019 10:43:55 -0700 Subject: [PATCH] WIP use doc_cfg for cross-platform documentation This commit demonstrates the use of the unstable doc_cfg feature to make cross-platform documentation. Properly annotated items will be visible in the documentation regardless of which platform it was built on. But there are still a few warts: * The feature is unstable, so it must be gated by a "nightly-docs" feature flag. * Rust-2015-style macros must be annotated individually, even if they're behind an annotated module. * Struct members, even private ones, must be #[cfg()] gated even if their struct is already gated. --- Cargo.toml | 7 +++++++ src/lib.rs | 9 +++++++-- src/sys/ioctl/bsd.rs | 14 ++++++++++++++ src/sys/ioctl/mod.rs | 10 +++++++++- src/ucontext.rs | 12 ++++++++++-- src/unistd.rs | 16 ++++++++++++---- 6 files changed, 59 insertions(+), 9 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index b04f9b51bc..a2991031c0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,6 +15,13 @@ exclude = [ "/bors.toml" ] +[package.metadata.docs.rs] +features = ["nightly-docs"] + +[features] +# For building documentation only; no functional change to the library. +nightly-docs = [] + [dependencies] libc = { git = "https://github.com/rust-lang/libc" } bitflags = "1.0" diff --git a/src/lib.rs b/src/lib.rs index ae3cc73413..7677d764b9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -14,6 +14,7 @@ #![deny(unstable_features)] #![deny(missing_copy_implementations)] #![deny(missing_debug_implementations)] +#![cfg_attr(feature = "nightly-docs", feature(doc_cfg))] // External crates #[macro_use] @@ -67,8 +68,12 @@ pub mod sched; pub mod sys; // This can be implemented for other platforms as soon as libc // provides bindings for them. -#[cfg(all(target_os = "linux", - any(target_arch = "x86", target_arch = "x86_64")))] +#[cfg(any(all(target_os = "linux", + any(target_arch = "x86", target_arch = "x86_64")), + all(feature = "nightly-docs", rustdoc)))] +#[cfg_attr(feature = "nightly-docs", + doc(cfg(all(target_os = "linux", + any(target_arch = "x86", target_arch = "x86_64")))))] pub mod ucontext; pub mod unistd; diff --git a/src/sys/ioctl/bsd.rs b/src/sys/ioctl/bsd.rs index 4c39fa6a05..7ffa086586 100644 --- a/src/sys/ioctl/bsd.rs +++ b/src/sys/ioctl/bsd.rs @@ -44,6 +44,20 @@ macro_rules! ioc { /// ioctl_write_int_bad!(kvm_create_vm, request_code_none!(KVMIO, 0x03)); /// # fn main() {} /// ``` +#[cfg(any(target_os = "dragonfly", + target_os = "freebsd", + target_os = "ios", + target_os = "macos", + target_os = "netbsd", + target_os = "openbsd", + all(feature = "nightly-docs", rustdoc)))] +#[cfg_attr(feature = "nightly-docs", + doc(cfg(any(target_os = "dragonfly", + target_os = "freebsd", + target_os = "ios", + target_os = "macos", + target_os = "netbsd", + target_os = "openbsd"))))] #[macro_export] macro_rules! request_code_none { ($g:expr, $n:expr) => (ioc!($crate::sys::ioctl::VOID, $g, $n, 0)) diff --git a/src/sys/ioctl/mod.rs b/src/sys/ioctl/mod.rs index 35d508b131..30ffdbbbf9 100644 --- a/src/sys/ioctl/mod.rs +++ b/src/sys/ioctl/mod.rs @@ -233,7 +233,15 @@ pub use self::linux::*; target_os = "ios", target_os = "macos", target_os = "netbsd", - target_os = "openbsd"))] + target_os = "openbsd", + all(feature = "nightly-docs", rustdoc)))] +#[cfg_attr(feature = "nightly-docs", + doc(cfg(any(target_os = "dragonfly", + target_os = "freebsd", + target_os = "ios", + target_os = "macos", + target_os = "netbsd", + target_os = "openbsd"))))] #[macro_use] mod bsd; diff --git a/src/ucontext.rs b/src/ucontext.rs index c94464d570..ff2bd07c3d 100644 --- a/src/ucontext.rs +++ b/src/ucontext.rs @@ -9,11 +9,16 @@ use sys::signal::SigSet; #[derive(Clone, Copy)] #[allow(missing_debug_implementations)] pub struct UContext { + #[cfg(all(target_os = "linux", + any(target_arch = "x86", target_arch = "x86_64")))] context: libc::ucontext_t, } impl UContext { - #[cfg(not(target_env = "musl"))] + #[cfg(any(not(target_env = "musl"), + all(feature = "nightly-docs", rustdoc)))] + #[cfg_attr(feature = "nightly-docs", + doc(cfg(not(target_env = "musl"))))] pub fn get() -> Result { let mut context: libc::ucontext_t = unsafe { mem::uninitialized() }; let res = unsafe { @@ -22,7 +27,10 @@ impl UContext { Errno::result(res).map(|_| UContext { context: context }) } - #[cfg(not(target_env = "musl"))] + #[cfg(any(not(target_env = "musl"), + all(feature = "nightly-docs", rustdoc)))] + #[cfg_attr(feature = "nightly-docs", + doc(cfg(not(target_env = "musl"))))] pub fn set(&self) -> Result<()> { let res = unsafe { libc::setcontext(&self.context as *const libc::ucontext_t) diff --git a/src/unistd.rs b/src/unistd.rs index a41c1392be..9f07768c73 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -333,7 +333,10 @@ pub fn getpgrp() -> Pid { /// /// No error handling is required as a thread id should always exist for any /// process, even if threads are not being used. -#[cfg(any(target_os = "linux", target_os = "android"))] +#[cfg(any(any(target_os = "linux", target_os = "android"), + all(feature = "nightly-docs", rustdoc)))] +#[cfg_attr(feature = "nightly-docs", + doc(cfg(any(target_os = "linux", target_os = "android"))))] #[inline] pub fn gettid() -> Pid { Pid(unsafe { libc::syscall(libc::SYS_gettid) as pid_t }) @@ -763,9 +766,14 @@ pub fn execvpe(filename: &CString, args: &[CString], env: &[CString]) -> Result< // Note for NetBSD and OpenBSD: although rust-lang/libc includes it (under // unix/bsd/netbsdlike/) fexecve is not currently implemented on NetBSD nor on // OpenBSD. -#[cfg(any(target_os = "android", - target_os = "linux", - target_os = "freebsd"))] +#[cfg(any(any(target_os = "android", + target_os = "linux", + target_os = "freebsd"), + all(feature = "nightly-docs", rustdoc)))] +#[cfg_attr(feature = "nightly-docs", + doc(cfg(any(target_os = "android", + target_os = "linux", + target_os = "freebsd"))))] #[inline] pub fn fexecve(fd: RawFd, args: &[CString], env: &[CString]) -> Result { let args_p = to_exec_array(args);