Remove target_os annotations from the docs.

The reasons not to use it are: * Items that aren't built on the platform for which the docs were built won't show up in the docs. For example, if you build the docs on FreeBSD, you won't see that there's a kmod module only available for Linux. * Some items are built with different signatures on different OSes. A "target_os" annotation won't tell the reader that. * Using #[cfg(any(docsrs, target_os=...))] is not a solution, because too many items will simply throw errors when generating the documentation that way. For example, every enum value in a libc_enum! invocation and every const in a libc_bitflags! invocation. * Annotating the docs with a bunch of OS notes gives readers a false sense of security. For the reasons noted above, those annotations will be incomplete, which might deter users from checking the docs built for their platform. So I think we should carefully remove all of those annotations from the docs. However, I'm leaving in place annotations about target_env and target_arch, because we don't build docs separately for all of those combinations.
nix-rust · Oct 17, 2021 · 83ea2f3 · 83ea2f3
1 parent 261fcb2
commit 83ea2f3
Show file tree

Hide file tree

Showing 30 changed files with 638 additions and 36 deletions.
diff --git a/src/dir.rs b/src/dir.rs
@@ -5,6 +5,7 @@ use std::os::unix::io::{AsRawFd, IntoRawFd, RawFd};
 use std::ptr;
 use std::ffi;
 use crate::sys;
+use cfg_if::cfg_if;
 
 #[cfg(target_os = "linux")]
 use libc::{dirent64 as dirent, readdir64_r as readdir_r};
@@ -186,34 +187,24 @@ pub enum Type {
 
 impl Entry {
     /// Returns the inode number (`d_ino`) of the underlying `dirent`.
-    #[cfg(any(target_os = "android",
-              target_os = "emscripten",
-              target_os = "fuchsia",
-              target_os = "haiku",
-              target_os = "illumos",
-              target_os = "ios",
-              target_os = "l4re",
-              target_os = "linux",
-              target_os = "macos",
-              target_os = "solaris"))]
-    pub fn ino(&self) -> u64 {
-        self.0.d_ino as u64
-    }
-
-    /// Returns the inode number (`d_fileno`) of the underlying `dirent`.
-    #[cfg(not(any(target_os = "android",
-                  target_os = "emscripten",
-                  target_os = "fuchsia",
-                  target_os = "haiku",
-                  target_os = "illumos",
-                  target_os = "ios",
-                  target_os = "l4re",
-                  target_os = "linux",
-                  target_os = "macos",
-                  target_os = "solaris")))]
     #[allow(clippy::useless_conversion)]    // Not useless on all OSes
     pub fn ino(&self) -> u64 {
-        u64::from(self.0.d_fileno)
+        cfg_if! {
+            if #[cfg(any(target_os = "android",
+                         target_os = "emscripten",
+                         target_os = "fuchsia",
+                         target_os = "haiku",
+                         target_os = "illumos",
+                         target_os = "ios",
+                         target_os = "l4re",
+                         target_os = "linux",
+                         target_os = "macos",
+                         target_os = "solaris"))] {
+                self.0.d_ino as u64
+            } else {
+                u64::from(self.0.d_fileno)
+            }
+        }
     }
 
     /// Returns the bare file name of this directory entry without any other leading path component.

diff --git a/src/fcntl.rs b/src/fcntl.rs
@@ -53,11 +53,13 @@ libc_bitflags!(
         O_ACCMODE;
         /// Use alternate I/O semantics.
         #[cfg(target_os = "netbsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_ALT_IO;
         /// Open the file in append-only mode.
         O_APPEND;
         /// Generate a signal when input or output becomes possible.
         #[cfg(not(any(target_os = "illumos", target_os = "solaris")))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_ASYNC;
         /// Closes the file descriptor once an `execve` call is made.
         ///
@@ -71,9 +73,11 @@ libc_bitflags!(
                   target_os = "freebsd",
                   target_os = "linux",
                   target_os = "netbsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_DIRECT;
         /// If the specified path isn't a directory, fail.
         #[cfg(not(any(target_os = "illumos", target_os = "solaris")))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_DIRECTORY;
         /// Implicitly follow each `write()` with an `fdatasync()`.
         #[cfg(any(target_os = "android",
@@ -82,11 +86,13 @@ libc_bitflags!(
                   target_os = "macos",
                   target_os = "netbsd",
                   target_os = "openbsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_DSYNC;
         /// Error out if a file was not created.
         O_EXCL;
         /// Open for execute only.
         #[cfg(target_os = "freebsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_EXEC;
         /// Open with an exclusive file lock.
         #[cfg(any(target_os = "dragonfly",
@@ -96,6 +102,7 @@ libc_bitflags!(
                   target_os = "netbsd",
                   target_os = "openbsd",
                   target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_EXLOCK;
         /// Same as `O_SYNC`.
         #[cfg(any(target_os = "dragonfly",
@@ -106,30 +113,37 @@ libc_bitflags!(
                   target_os = "netbsd",
                   target_os = "openbsd",
                   target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_FSYNC;
         /// Allow files whose sizes can't be represented in an `off_t` to be opened.
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_LARGEFILE;
         /// Do not update the file last access time during `read(2)`s.
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_NOATIME;
         /// Don't attach the device as the process' controlling terminal.
         #[cfg(not(target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_NOCTTY;
         /// Same as `O_NONBLOCK`.
         #[cfg(not(target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_NDELAY;
         /// `open()` will fail if the given path is a symbolic link.
         O_NOFOLLOW;
         /// When possible, open the file in nonblocking mode.
         O_NONBLOCK;
         /// Don't deliver `SIGPIPE`.
         #[cfg(target_os = "netbsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_NOSIGPIPE;
         /// Obtain a file descriptor for low-level access.
         ///
         /// The file itself is not opened and other file operations will fail.
         #[cfg(any(target_os = "android", target_os = "linux", target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_PATH;
         /// Only allow reading.
         ///
@@ -141,9 +155,11 @@ libc_bitflags!(
         O_RDWR;
         /// Similar to `O_DSYNC` but applies to `read`s instead.
         #[cfg(any(target_os = "linux", target_os = "netbsd", target_os = "openbsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_RSYNC;
         /// Skip search permission checks.
         #[cfg(target_os = "netbsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_SEARCH;
         /// Open with a shared file lock.
         #[cfg(any(target_os = "dragonfly",
@@ -153,17 +169,21 @@ libc_bitflags!(
                   target_os = "netbsd",
                   target_os = "openbsd",
                   target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_SHLOCK;
         /// Implicitly follow each `write()` with an `fsync()`.
         #[cfg(not(target_os = "redox"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_SYNC;
         /// Create an unnamed temporary file.
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_TMPFILE;
         /// Truncate an existing regular file to 0 length if it allows writing.
         O_TRUNC;
         /// Restore default TTY attributes.
         #[cfg(target_os = "freebsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         O_TTY_INIT;
         /// Only allow writing.
         ///

diff --git a/src/lib.rs b/src/lib.rs
@@ -40,6 +40,7 @@
 //! * `zerocopy` - APIs like `sendfile` and `copy_file_range`
 #![crate_name = "nix"]
 #![cfg(unix)]
+#![cfg_attr(docsrs, doc(cfg(all())))]
 #![allow(non_camel_case_types)]
 #![cfg_attr(test, deny(warnings))]
 #![recursion_limit = "500"]

diff --git a/src/mount/bsd.rs b/src/mount/bsd.rs
@@ -20,29 +20,36 @@ libc_bitflags!(
     pub struct MntFlags: c_int {
         /// ACL support enabled.
         #[cfg(any(target_os = "netbsd", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_ACLS;
         /// All I/O to the file system should be done asynchronously.
         MNT_ASYNC;
         /// dir should instead be a file system ID encoded as “FSID:val0:val1”.
         #[cfg(target_os = "freebsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_BYFSID;
         /// Force a read-write mount even if the file system appears to be
         /// unclean.
         MNT_FORCE;
         /// GEOM journal support enabled.
         #[cfg(target_os = "freebsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_GJOURNAL;
         /// MAC support for objects.
         #[cfg(any(target_os = "macos", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_MULTILABEL;
         /// Disable read clustering.
         #[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_NOCLUSTERR;
         /// Disable write clustering.
         #[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_NOCLUSTERW;
         /// Enable NFS version 4 ACLs.
         #[cfg(target_os = "freebsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_NFS4ACLS;
         /// Do not update access times.
         MNT_NOATIME;
@@ -52,6 +59,7 @@ libc_bitflags!(
         MNT_NOSUID;
         /// Do not follow symlinks.
         #[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_NOSYMFOLLOW;
         /// Mount read-only.
         MNT_RDONLY;
@@ -62,6 +70,7 @@ libc_bitflags!(
         ///
         /// See [mksnap_ffs(8)](https://www.freebsd.org/cgi/man.cgi?query=mksnap_ffs)
         #[cfg(any(target_os = "macos", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_SNAPSHOT;
         /// Using soft updates.
         #[cfg(any(
@@ -70,10 +79,12 @@ libc_bitflags!(
                 target_os = "netbsd",
                 target_os = "openbsd"
         ))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_SOFTDEP;
         /// Directories with the SUID bit set chown new files to their own
         /// owner.
         #[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_SUIDDIR;
         /// All I/O to the file system should be done synchronously.
         MNT_SYNCHRONOUS;
@@ -83,12 +94,14 @@ libc_bitflags!(
                 target_os = "freebsd",
                 target_os = "netbsd"
         ))]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_UNION;
         /// Indicates that the mount command is being applied to an already
         /// mounted file system.
         MNT_UPDATE;
         /// Check vnode use counts.
         #[cfg(target_os = "freebsd")]
+        #[cfg_attr(docsrs, doc(cfg(all())))]
         MNT_NONBUSY;
     }
 );
@@ -182,13 +195,15 @@ pub type NmountResult = std::result::Result<(), NmountError>;
 /// * [`nmount(2)`](https://www.freebsd.org/cgi/man.cgi?query=nmount)
 /// * [`nullfs(5)`](https://www.freebsd.org/cgi/man.cgi?query=nullfs)
 #[cfg(target_os = "freebsd")]
+#[cfg_attr(docsrs, doc(cfg(all())))]
 #[derive(Debug, Default)]
 pub struct Nmount<'a>{
     iov: Vec<IoVec<&'a [u8]>>,
     is_owned: Vec<bool>,
 }
 
 #[cfg(target_os = "freebsd")]
+#[cfg_attr(docsrs, doc(cfg(all())))]
 impl<'a> Nmount<'a> {
     /// Add an opaque mount option.
     ///

diff --git a/src/mount/mod.rs b/src/mount/mod.rs
@@ -1,5 +1,6 @@
 //! Mount file systems
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[cfg_attr(docsrs, doc(cfg(all())))]
 mod linux;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
@@ -10,6 +11,7 @@ pub use self::linux::*;
           target_os = "macos",
           target_os = "netbsd",
           target_os = "openbsd"))]
+#[cfg_attr(docsrs, doc(cfg(all())))]
 mod bsd;
 
 #[cfg(any(target_os = "dragonfly",

diff --git a/src/mqueue.rs b/src/mqueue.rs
@@ -37,8 +37,10 @@ pub struct MqAttr {
 // x32 compatibility
 // See https://sourceware.org/bugzilla/show_bug.cgi?id=21279
 #[cfg(all(target_arch = "x86_64", target_pointer_width = "32"))]
+#[cfg_attr(docsrs, doc(cfg(all())))]
 pub type mq_attr_member_t = i64;
 #[cfg(not(all(target_arch = "x86_64", target_pointer_width = "32")))]
+#[cfg_attr(docsrs, doc(cfg(all())))]
 pub type mq_attr_member_t = libc::c_long;
 
 impl MqAttr {